API

The Genius class inherits this class, and it’s recommended to call the methods using the Genius class rather than accessing this class directly.

class lyricsgenius.API(client_access_token, response_format='plain', timeout=5, sleep_time=0.5)

Bases: lyricsgenius.api.base.Sender

Genius API. The API class is in charge of making all the requests to the developers’ API (api.genius.com) Use the methods of this class if you already have information such as song ID to make direct requests to the API. Otherwise the Genius class provides a friendlier front-end to search and retrieve data from Genius.com.

All methods of this class are available through the Genius class.
Parameters
  • client_access_token (str) – API key provided by Genius.

  • response_format (str, optional) – API response format (dom, plain, html).

  • timeout (int, optional) – time before quitting on response (seconds).

  • sleep_time (str, optional) – time to wait between requests.

response_format

API response format (dom, plain, html).

Type

str, optional

timeout

time before quitting on response (seconds).

Type

int, optional

sleep_time

time to wait between requests.

Type

str, optional

Returns

An object of the API class.

Return type

API

song(song_id, text_format=None)

Gets data for a specific song.

Parameters
  • song_id (int) – Genius song ID

  • text_format (str, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns

Song details from Genius.

Return type

dict

Examples

genius = Genius(token)
song = genius.song(2857381)
print(song['full_title'])

Note

This pure API method is used for fetching songs when you have their ID, and only makes a request to the API, therefore provides no lyrics. If you want the lyrics as well, use Genius.search_song() instead.

artist(artist_id, text_format=None)

Gets data for a specific artist.

Parameters
  • artist_id (int) – Genius artist ID

  • text_format (str, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns

dict

Examples

genius = Genius(token)
artist = genius.artist(380491)
print(artist['name'])
artist_songs(artist_id, per_page=None, page=None, sort='title')

Gets artist’s songs.

Parameters
  • artist_id (int) – Genius artist ID

  • sort (str, optional) – Sorting preference. Either based on ‘title’ or ‘popularity’.

  • per_page (int, optional) – Number of results to return per request. It can’t be more than 50.

  • page (int, optional) – Paginated offset (number of the page).

Returns

dict

Examples

# getting all artist songs based on popularity
genius = Genius(token)
page = 1
songs = []
while page:
    request = genius.artist_songs(380491,
                                  sort='popularity',
                                  per_page=50,
                                  page=page)
songs.extend(request['songs'])
page = request['next_page']
least_popular_song = songs[-1]['title']


# getting songs 11-15
songs = genius.artist_songs(380491, per_page=5, page=3)
referents(song_id=None, web_page_id=None, created_by_id=None, per_page=None, page=None, text_format=None)

Gets item’s referents

Parameters
  • song_id (int, optional) – song ID

  • web_page_id (int, optional) – web page ID

  • created_by_id (int, optional) – User ID of the contributer who created the annotation(s).

  • per_page (int, optional) – Number of results to return per page. It can’t be more than 50.

  • text_format (str, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns

dict

Note

You may pass only one of song_id and web_page_id, not both.

Examples

# getting all verified annotations of a song (artist annotations)
genius = Genius(token)
request = genius.referents(song_id=235729,
                           per_page=50)
verified = [y for x in request['referents']
            for y in x['annotations'] if y['verified']]
annotation(annotation_id, text_format=None)

Gets data for a specific annotation.

Parameters
  • annotation_id (int) – annotation ID

  • text_format (str, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns

dict

search_songs(search_term, per_page=None, page=None)

Searches songs hosted on Genius.

Parameters
  • search_term (str) – A term to search on Genius.

  • per_page (int, optional) – Number of results to return per page. It can’t be more than 5 for this method.

  • page (int, optional) – Number of the page.

Returns

dict