Java Genius API Wrapper

This is a java wrapper for the Genius API.
This library can be used with Java 11 or newer.

Download

Be sure to replace the VERSION key below with the version shown above!

<repository>
    <id>spoocyDev-releases</id>
    <name>Coding Stube Repository</name>
    <url>https://repo.coding-stube.de/releases</url>
</repository>

<dependency>
    <groupId>dev.spoocy.genius</groupId>
    <artifactId>GeniusAPI</artifactId>
    <version>VERSION</version>
</dependency>

Authentication

Important

You will need to create a Genius API Client. You can do so at https://genius.com/api-clients

See https://docs.genius.com/#/authentication-h1 for more information about Authentication.

---

Authenticating to the Genius API by using your Client access token:

• client_id: Your application's Client ID
• client_secret: Your application's Client Secret
• client_access_token: Your application's Client Access Token (can be found on the Genius API Client management page)

GeniusClient client = new GeniusClientBuilder()
        
        // Set your Client ID
        .setClientId("your_client_id")       
        
        // Set your Client Secret
        .setClientSecret("your_client_secret")
        
        // Set the Auth Type you want to use. In this case by providing a Client Access Token
        .setAuthType(GeniusClientBuilder.AuthType.CLIENT_ACCESS_TOKEN)
        
        // Set the User Agent
        .setUserAgent("Mozilla/5.0")
        
        .build();

After building the Client, you will need to providing the client with the Client Access Token.

// Set the Client Access Token for the client to use. Before doing this, no requests can be made.
client.setAuthorizationCode("your_client_access_token");

Implementation Example: AccessTokenExample

---

Authenticating to the Genius API by getting and providing an Access Token:

Used for making API calls on behalf of individual users.

• client_id: Your application's Client ID
• client_secret: Your application's Client Secret
• redirect_uri: The URI Genius will redirect the user to after they've authorized your application; it must be the same as the one set for the API Client on the management page
• state: A value that will be returned with the code redirect for maintaining arbitrary state through the authorization process

GeniusClient client = new GeniusClientBuilder()
        
        // Set your Client ID
        .setClientId("your_client_id")
        
        // Set your Client Secret
        .setClientSecret("your_client_secret")
        
        // Set the Auth Type you want to use. In this case by getting an Access Token
        .setAuthType(GeniusClientBuilder.AuthType.AUTHORIZATION_CODE)
        
        // Set your redirect URI
        .setCallbackUrl("your_redirect_uri")
        
        // Set the User Agent
        .setUserAgent("Mozilla/5.0")
        
        .build();

After building the Client, you will need to authorize using the Authorization URL and providing the client with the code.

String SECRET_STATE = "100";                                // The state value to be returned with the code (see above)
String url = client.buildAuthorizationUrl(SECRET_STATE);    // Builds the Authorization URL using the provided credentials and the state

// Set the Authorization Code for the client to use. Before doing this, n qo requests can be made.
client.setAuthorizationCode("code_received_from_the_authorization_url");

Implementation Example: AuthorizationCodeExample

Usage

Getting a Lyrics of a song.

String url = "https://genius.com/Kendrick-lamar-humble-lyrics";
client.lyrics()                          // Get the lyrics of a song
    .setSongUrl(url)                     // Set the URL of the song
    .setSongName("Eine gute Frau")       // OR set the name of the song (if url is set, this will be ignored)
    .doOnError(e -> {
        System.out.println("Error while getting lyrics: " + e.getMessage());
    })
        .subscribe(lyrics -> {
            System.out.println(lyrics.getAsPlain());
        });

---

Searching for a list of song by providing a query.

client.search()
    
    // Set the query
    .setQuery("Kendrick Lamar")
    
    .subscribe(search -> {
        
        // Results might be empty if nothing is found
        if(search.getResults().isEmpty()) {
            System.out.println("No results found!");
            return;
        }
        
        // Search provides a list of results
        SearchSong firstResult = search.getResults().get(0);
        System.out.println(String.format("ID: %s", firstResult.getId()));
        System.out.println(String.format("Artist: %s", firstResult.getArtist().getName()));
        System.out.println(String.format("URL: %s", firstResult.getUrl()));
    });

---

Searching for a song by providing the id of a song.

client.searchSong()
    
    // Set the id of the song
    .setId("378195")
    
    .subscribe(song -> {
        System.out.println(String.format("Title: %s", song.getTitle()));
    });

---

Searching for a artist by providing the id of the artist.

client.searchArtist() 
    
    // Set the id of the song
    .setId("16775")
    
    .subscribe(artist -> {
        System.out.println(String.format("Name: %s", artist.getName()));
    });

---

Gettings Descriptions of Artists and Songs.

//Artists and Songs may have descriptions. For those you need to provide how you want those to be formatted.
client.searchSong()
    .setId("378195")
    
    // Set the format of the description
    .addFormat(DescriptionFormat.HTML)
    
    // You may add multiple formats
    .addFormat(DescriptionFormat.PLAIN)
    
    .subscribe(song -> {
         // You can only get Description if you provided the format, otherwise it will be null
        System.out.println(String.format("Description: %s", song.getDescription().getPlain()));
    });

Calling Results

Calling results in sync:

Search result = client.search().setQuery("Kendrick Lamar").execute();

Calling results in async:

client.search().setQuery("Kendrick Lamar").subscribe(search -> {
    System.out.println(search.getResults().get(0).getTitle());
});

Examples

The following examples are minimal implementations but show how the library works.

• Making Requests using a Client Access Token: link
• Making Requests using an Access Token: link