Genius

The Genius class provides a high-level interface to the Genius API. This class provides convenient access to the standard API, the public API, and additional features such as downloading lyrics.

class lyricsgenius.Genius(client_access_token, response_format='plain', timeout=5, sleep_time=0.5, verbose=True, remove_section_headers=False, skip_non_songs=True, excluded_terms=None, replace_default_terms=False)

Bases: lyricsgenius.api.api.API, lyricsgenius.api.api.PublicAPI

User-level interface with the Genius.com API and public API.

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.

  • verbose (bool, optional) – Turn printed messages on or off.

  • remove_section_headers (bool, optional) – If True, removes [Chorus], [Bridge], etc. headers from lyrics.

  • skip_non_songs (bool, optional) – If True, attempts to skip non-songs (e.g. track listings).

  • excluded_terms (list, optional) – extra terms for flagging results as non-lyrics.

  • replace_default_terms (list, optional) – if True, replaces default excluded terms with user’s. Default excluded terms are listed below.

verbose

Turn printed messages on or off.

Type

bool, optional

remove_section_headers

If True, removes [Chorus], [Bridge], etc. headers from lyrics.

Type

bool, optional

skip_non_songs

If True, attempts to skip non-songs (e.g. track listings).

Type

bool, optional

excluded_terms

extra terms for flagging results as non-lyrics.

Type

list, optional

replace_default_terms

if True, replaces default excluded terms with user’s.

Type

list, optional

Returns

Genius

Note

Default excluded terms are the following regular expressions: tracks?list, album art(work)?, liner notes, booklet, credits, interview, skit, instrumental, and setlist.

Album Methods

Genius.album

Gets data for a specific album.

Genius.albums_charts

Gets the album charts.

Genius.album_comments

Gets the comments on an album page.

Genius.album_cover_arts

Gets cover arts of a specific album.

Genius.album_leaderboard

Gets the leaderboard of an album.

Genius.album_tracks

Gets the tracks of a specific album.
Genius.album(album_id, text_format=None)

Gets data for a specific album.

Parameters

  • album_id (int) – Genius album ID

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

Returns

dict

Examples

genius = Genius(token)
song = genius.search_song(378195)
album_id = song['album']['id']
album = genius.album(album_id)
print(album['name'])
Genius.albums_charts(time_period='day', chart_genre='all', per_page=None, page=None, text_format=None)

Gets the album charts.

Alias for charts().

Parameters

  • time_period (str, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).

  • chart_genre (str, optional) – The genre of the results.

  • 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).

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

Returns

dict

Genius.album_comments(album_id, per_page=None, page=None, text_format=None)

Gets the comments on an album page.

Parameters

  • album_id (int) – Genius album ID

  • 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).

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

Returns

dict

Genius.album_cover_arts(album_id, text_format=None)

Gets cover arts of a specific album.

Alias for cover_arts.

Parameters

  • album_id (int) – Genius album ID

  • text_format (str, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’). Defines the text formatting for the annotation of the cover arts, if there are any.

Returns

dict

Examples

Downloading album’s cover art:

import requests

genius = Genius(token)
res = genius.album_cover_arts(104614)
cover_art = requests.get(res['cover_arts'][0]['image_url'])
Genius.album_leaderboard(album_id, per_page=None, page=None)

Gets the leaderboard of an album.

This method returns the album’s top contributors.

Parameters

  • album_id (int) – Genius album ID

  • 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

Genius.album_tracks(album_id, per_page=None, page=None, text_format=None)

Gets the tracks of a specific album.

Parameters

  • album_id (int) – Genius album ID

  • 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).

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

Returns

dict

Annotation Methods

Genius.annotation

Searches songs hosted on Genius.

Genius.annotation_edits

Gets the edits on annotation (its versions).

Genius.annotation_comments

Gets the comments on an annotation.
Genius.annotation(annotation_id, text_format=None, public_api=False)

Searches songs hosted on Genius.

Parameters

  • annotation_id (int) – annotation ID

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

  • public_api (bool, optional) – If True, performs the search using the public API endpoint.

Returns

dict

Note

Using the public API will return the same annotation and referent but with more fields:

  • API: Annotation will have 19 fields and the referent 15.

  • Public API: Annotation will have 32 fields and referent 20.

Genius.annotation_edits(annotation_id, text_format=None)

Gets the edits on annotation (its versions).

Parameters

  • annotation_id (int) – Genius annotation ID

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

Returns

dict

Genius.annotation_comments(annotation_id, per_page=None, page=None, text_format=None)

Gets the comments on an annotation.

Parameters

  • annotation_id (int) – Genius annotation ID

  • 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).

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

Returns

dict

Article Methods

Genius.article

Gets data for a specific article.

Genius.article_comments

Gets the comments on an article.

Genius.latest_articles

Gets the latest articles on the homepage.
Genius.article(article_id, text_format=None)

Gets data for a specific article.

Parameters

  • article_id (int) – Genius article ID

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

Returns

dict

Genius.article_comments(article_id, per_page=None, page=None, text_format=None)

Gets the comments on an article.

Parameters

  • article_id (int) – Genius article ID

  • 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).

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

Returns

dict

Genius.latest_articles(per_page=None, page=None, text_format=None)

Gets the latest articles on the homepage. This method will return the featured articles that are placed on top of the Genius.com page.

Parameters

  • article_id (int) – Genius article ID

  • 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).

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

Returns

dict

Artist Methods

Genius.artist

Gets data for a specific artist.

Genius.artist_activity

Gets activities on artist’s songs.

Genius.artist_albums

Gets artist’s albums.

Genius.artist_contribution_opportunities

Gets contribution opportunities related to the artist.

Genius.artist_followers

Gets artist’s followers.

Genius.artist_leaderboard

Gets artist’s top scholars.

Genius.artist_songs

Gets artist’s songs.

Genius.save_artists

Saves lyrics from multiple Artist objects as JSON object.

Genius.search_artist_songs

Searches artist’s songs.
Genius.artist(artist_id, text_format=None, public_api=False)

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’).

  • public_api (bool, optional) – If True, performs the search using the public API endpoint.

Returns

dict

Note

Using the public API will return the same artist but with more fields:

  • API: Result will have 19 fields.

  • Public API: Result will have 24 fields.

Genius.artist_activity(artist_id, per_page=None, page=None, text_format=None)

Gets activities on artist’s songs.

Parameters

  • artist_id (int) – Genius artist ID

  • 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).

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

Returns

dict

Genius.artist_albums(artist_id, per_page=None, page=None)

Gets artist’s albums.

Parameters

  • artist_id (int) – Genius artist ID

  • 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

Genius.artist_contribution_opportunities(artist_id, per_page=None, next_curosr=None, text_format=None)

Gets contribution opportunities related to the artist.

Parameters

  • artist_id (int) – Genius artist ID

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

  • next_cursor (int, optional) – Paginated offset (address of the next cursor).

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

Returns

dict

Warning

This method requires a logged in user and will raise NotImplementedError.

Genius.artist_followers(artist_id, per_page=None, page=None)

Gets artist’s followers.

Parameters

  • artist_id (int) – Genius artist ID

  • 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

Genius.artist_leaderboard(artist_id, per_page=None, page=None)

Gets artist’s top scholars.

Parameters

  • artist_id (int) – Genius artist ID

  • 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

Genius.artist_songs(artist_id, per_page=None, page=None, sort='title', public_api=False)

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).

  • public_api (bool, optional) – If True, performs the search using the public API endpoint.

Returns

dict

Note

Using the public API will return the same songs but with more fields:

  • API: Song will have 17 fields.

  • Public API: Song will have 21 fields.

Genius.save_artists(artists, filename='artist_lyrics', overwrite=False, ensure_ascii=True)

Saves lyrics from multiple Artist objects as JSON object.

Parameters

  • artists (list) – List of Artist objects to save lyrics from.

  • filename (str, optional) – Name of the output file.

  • overwrite (bool, optional) – Overwrites preexisting file if True. Otherwise prompts user for input.

  • ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Examples

genius = Genius(token)
a = search_artist('Andy Shauf')
b = search_artist('Queen', max_song=10)
c = search_artist('The Beatles', max_songs=1)

genius.save_artists(artists=[a, b, c], filename='abc', overwrite=True)
Genius.search_artist_songs(artist_id, search_term, per_page=None, page=None, sort='popularity')

Searches artist’s songs.

Parameters

  • artist_id (int) – Genius artist ID

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

  • 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).

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

Returns

dict

Cover Art Methods

Genius.cover_arts

Gets the cover arts of an album or a song.
Genius.cover_arts(album_id=None, song_id=None, text_format=None)

Gets the cover arts of an album or a song. You must supply one of album_id or song_id.

Parameters

  • album_id (int, optional) – Genius album ID

  • song_id (int, optional) – Genius song ID

  • text_format (str, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’). Defines the text formatting for the annotation of the cover arts, if there are any.

Returns

dict

Discussion Methods

Genius.discussion(disscussion_id, text_format=None)

Gets data for a specific discussion.

Parameters

  • disscussion_id (int) – Genius discussion ID

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

Returns

dict

Genius.discussion_replies(disscussion_id, per_page=None, page=None, text_format=None)

Gets the replies on a discussion.

Parameters

  • disscussion_id (int) – Genius discussion ID

  • 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).

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

Returns

dict

Leaderboard Methods

Genius.leaderboard

Gets the Genius community leaderboard.

Genius.charts

Gets the Genius charts.
Genius.leaderboard(time_period='day', per_page=None, page=None, text_format=None)

Gets the Genius community leaderboard.

This method gets data of the community charts on the Genius.com page.

Parameters

  • time_period (str, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).

  • 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).

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

Returns

dict

Genius.charts(time_period='day', chart_genre='all', per_page=None, page=None, text_format=None, type_='songs')

Gets the Genius charts.

This method gets data of the chart on the Genius.com page.

Parameters

  • time_period (str, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).

  • chart_genre (str, optional) – The genre of the results.

  • 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).

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

  • type (int, optional) – The type to get the charts for. (‘songs’, ‘albums’, ‘artists’ or ‘referents’).

Returns

dict

Note

The referents mentioned in the description of the type_ argument is shown as Lyrics in the drop-down menu on Genius.com where you can choose the Type.

Question & Answer Methods

Genius.questions

Gets the questions on an album or a song.
Genius.questions(album_id=None, song_id=None, per_page=None, page=None, state=None, text_format=None)

Gets the questions on an album or a song. You must supply one of album_id or song_id.

Parameters

  • time_period (str, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).

  • 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).

  • state (str, optional) – State of the question.

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

Returns

dict

Referent Methods

Genius.referent

Gets data of one or more referents.

Genius.referents

Gets item’s referents

Genius.referents_charts

Gets the referents (lyrics) charts.
Genius.referent(referent_ids, text_format=None)

Gets data of one or more referents. This method can get multiple referents in one call, thus increasing performance.

Parameters

  • referent_ids (list) – A list of referent IDs.

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

Returns

dict

Note

Using this method you can get the referent itself instead of the referents of a song or webpage which is what referents() gets.

Genius.referents(song_id=None, web_page_id=None, created_by_id=None, per_page=None, page=None, text_format=None, public_api=False)

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’).

  • public_api (bool, optional) – If True, performs the search using the public API endpoint.

Returns

dict

Note

Using the public API will return the same referents but with more fields:

  • API: Referent will have 15 fields.

  • Public API: Referent will have 20 fields.

Genius.referents_charts(time_period='day', chart_genre='all', per_page=None, page=None, text_format=None)

Gets the referents (lyrics) charts.

Alias for charts().

Parameters

  • time_period (str, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).

  • chart_genre (str, optional) – The genre of the results.

  • 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).

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

Returns

dict

Search Methods

Genius.search

Searches Genius.

Genius.search_all

Searches all types.

Genius.search_albums

Searches the albums on Genius.

Genius.search_artist

Searches for a specific artist and gets their songs.

Genius.search_artists

Searches the artists on Genius.

Genius.search_lyrics

Searches the lyrics on Genius.

Genius.search_song

Searches for a specific song and gets its lyrics.

Genius.search_songs

Searches songs hosted on Genius.

Genius.search_users

Searches the users on Genius.

Genius.search_videos

Searches the videos on Genius.
Genius.search(search_term, per_page=None, page=None, type_='')

Searches Genius.

Parameters

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

  • 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).

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

  • type (str, optional) – Type of item to search for (‘song’, ‘lyric’, ‘artist’, ‘album’, ‘video’, ‘article’, ‘user’ or ‘multi’).

Returns

dict

Note

Specifying no type_ parameter (which defaults to '') or setting it as song will return the same results. Both will return songs. The only different is they return the hits in different keys:

  • type_='': response['hits']

  • type_='song': response['sections'][0]['hits']

By Setting the type as multi the method will perform a search for all the other types and return an extra section called top hits.

Note

Instead of calling this method directly and specifying a type, you can use the alias methods.

Genius.search_all(search_term, per_page=None, page=None)

Searches all types. Including: albums, articles, lyrics, songs, users and videos.

Alias for search()

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

Note

This method will also return a top hits section alongside other types.

Genius.search_albums(search_term, per_page=None, page=None)

Searches the albums on Genius.

Alias for search()

Parameters

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

  • 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).

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

Returns

dict

Genius.search_artist(artist_name, max_songs=None, sort='popularity', per_page=20, get_full_info=True, allow_name_change=True, artist_id=None, include_features=False)

Searches for a specific artist and gets their songs.

This method looks for the artist by the name or by the ID if it’s provided in artist_id. It returrns an Artist object if the search is successful. If allow_name_change is True, the name of the artist is changed to the artist name on Genius.

Parameters

  • artist_name (str`|:obj:`int) – Name of the artist to search for.

  • (obj (max_songs) – int, optional): Maximum number of songs to search for.

  • sort (str, optional) – Sort by ‘title’ or ‘popularity’.

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

  • get_full_info (bool, optional) – Get full info for each song (slower).

  • allow_name_change (bool, optional) – If True, search attempts to switch to intended artist name.

  • artist_id (int, optional) – Allows user to pass an artist ID.

  • include_features (bool, optional) – If True, includes tracks featuring the artist.

Returns

Artist object containing artist’s songs.

Return type

Artist

Examples

# printing the lyrics of all of the artist's songs
genius = Genius(token)
artist = genius.search_artist('Andy Shauf')
for song in artist.songs:
    print(song.lyrics)

Visit Aritst for more examples.

Genius.search_artists(search_term, per_page=None, page=None)

Searches the artists on Genius.

Alias for search()

Parameters

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

  • 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).

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

Returns

dict

Genius.search_lyrics(search_term, per_page=None, page=None)

Searches the lyrics on Genius.

Alias for search()

Parameters

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

  • 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).

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

Returns

dict

Genius.search_song(title, artist='', get_full_info=True)

Searches for a specific song and gets its lyrics.

Parameters

  • title (str) – Song title to search for.

  • artist (str, optional) – Name of the artist.

  • get_full_info (bool, optional) – Get full info for each song (slower).

Returns

On success, the song object is returned, otherwise None.

Return type

Song | None

Tip

Set Genius.verbose to True to read why the search fails.

Examples

genius = Genius(token)
artist = genius.search_artist('Andy Shauf', max_songs=0)
song = genius.search_song('Toy You', artist.name)
# same as: song = genius.search_song('To You', 'Andy Shauf')
print(song['lyrics'])
Genius.search_songs(search_term, per_page=None, page=None, public_api=False)

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.

  • public_api (bool, optional) – If True, performs the search using the public API endpoint.

Returns

dict

Note

Using the API or the public API returns the same results. The only difference is in the number of values each API returns.

  • API: Each song has 17 fields and songs are accessable through response['hits']

  • Public API: Each song has 21 fields and songs are accessible through response['sections'][0]['hits']

Genius.search_users(search_term, per_page=None, page=None)

Searches the users on Genius.

Alias for search()

Parameters

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

  • 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).

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

Returns

dict

Genius.search_videos(search_term, per_page=None, page=None)

Searches the videos on Genius.

Alias for search()

Parameters

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

  • 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).

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

Returns

dict

Song Methods

Genius.song

Gets data for a specific song.

Genius.song_activity

Gets activities on a song.

Genius.song_annotations

Return song’s annotations with associated fragment in list of tuple.

Genius.song_comments

Gets the comments on a song.

Genius.song_contributors

Gets the contributors of a song.

Genius.lyrics

Uses BeautifulSoup to scrape song info off of a Genius song URL
Genius.song(song_id, text_format=None, public_api=False)

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’).

  • public_api (bool, optional) – If True, performs the search using the public API endpoint.

Returns

dict

Note

Using the public API will return the same song but with more fields:

  • API: Song will have 39 fields.

  • Public API: Song will have 68 fields.

Genius.song_activity(song_id, per_page=None, page=None, text_format=None)

Gets activities on a song.

Parameters

  • song_id (int) – Genius song ID

  • 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).

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

Returns

dict

Genius.song_annotations(song_id, text_format=None, public_api=True)

Return song’s annotations with associated fragment in list of tuple.

Parameters

  • song_id (int) – song ID

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

  • public_api (bool, optional) – If True, performs the search using the public API endpoint.

Returns

list of tuples(fragment, [annotations])

Return type

list

Note

This method uses Genius.referents(), but provides convenient access to fragments (annotated text) and the corresponding annotations (Some fragments may have more than one annotation, because sometimes both artists and Genius users annotate them).

Genius.song_comments(song_id, per_page=None, page=None, text_format=None)

Gets the comments on a song.

Parameters

  • song_id (int) – Genius song ID

  • 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).

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

Returns

dict

Genius.song_contributors(song_id)

Gets the contributors of a song.

This method will return users who have contributed to this song by editing lyrics or song details.

Parameters

song_id (int) – Genius song ID

Returns

dict

Genius.lyrics(urlthing)

Uses BeautifulSoup to scrape song info off of a Genius song URL

Parameters

urlthing (str | int) – Song ID or song URL.

Returns

str If it can find the lyrics, otherwise None

Return type

str |‌ None

Note

If you pass a song ID, the method will have to make an extra request to obtain the song’s URL and scrape the lyrics off of it. So it’s best to pass the method a song’s URL.

If you want to get a song’s lyrics by searching for it, use Genius.search_song() instead.

Note

This method removes the song headers based on the value of the remove_section_headers attribute.

User Methods

Genius.user

Gets data for a specific user.

Genius.user_accomplishments

Gets user’s accomplishments.

Genius.user_following

Gets the accounts user follows.

Genius.user_followers

Gets user’s followers.

Genius.user_contributions

Gets user’s contributions.

Genius.user_annotations

Gets user’s annotations.

Genius.user_articles

Gets user’s articles.

Genius.user_pyongs

Gets user’s Pyongs.

Genius.user_questions_and_answers

Gets user’s Q&As.

Genius.user_suggestions

Gets user’s suggestions (comments).

Genius.user_transcriptions

Gets user’s transcriptions.

Genius.user_unreviewed

Gets user’s unreviewed annotations.
Genius.user(user_id, text_format=None)

Gets data for a specific user.

Parameters

  • user_id (int) – Genius user ID

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

Returns

dict

Genius.user_accomplishments(user_id, per_page=None, next_cursor=None)

Gets user’s accomplishments.

This methods gets the section titled “TOP ACCOMPLISHMENTS” in the user’s profile.

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

Returns

dict

Genius.user_following(user_id, per_page=None, page=None)

Gets the accounts user follows.

Parameters

  • user_id (int) – Genius user ID

  • 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

Genius.user_followers(user_id, per_page=None, page=None)

Gets user’s followers.

Parameters

  • user_id (int) – Genius user ID

  • 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

Genius.user_contributions(user_id, per_page=None, next_cursor=None, sort=None, text_format=None, type_=None)

Gets user’s contributions.

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

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

  • type (int, optional) – Type of the contribution (‘annotations’, ‘articles’, ‘pyongs’, ‘questions_and_answers’, ‘comments’, ‘transcriptions’ or ‘unreviewed annotations’).

Returns

dict

Note

Not all types support a sorting preference. Setting the sort for these types won’t result in erros, but won’t make a difference in the results either. To find out which types support which features, look at the alias methods.

Note

Setting no value for the type_ will return the user’s contributions (regardless of its type) in chronological order; just like visting a user’s profile page and scrolling down, looking at their contributions over time.

Genius.user_annotations(user_id, per_page=None, next_cursor=None, sort='popularity', text_format=None)

Gets user’s annotations.

Alias for user_contributions()

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

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

Returns

dict

Genius.user_articles(user_id, per_page=None, next_cursor=None, sort='popularity', text_format=None)

Gets user’s articles.

Alias for user_contributions()

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

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

Returns

dict

Genius.user_pyongs(user_id, per_page=None, next_cursor=None, text_format=None)

Gets user’s Pyongs.

Alias for user_contributions()

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

Returns

dict

Genius.user_questions_and_answers(user_id, per_page=None, next_cursor=None, text_format=None)

Gets user’s Q&As.

Alias for user_contributions()

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

Returns

dict

Genius.user_suggestions(user_id, per_page=None, next_cursor=None, text_format=None)

Gets user’s suggestions (comments).

Alias for user_contributions()

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

Returns

dict

Genius.user_transcriptions(user_id, per_page=None, next_cursor=None, sort='popularity', text_format=None)

Gets user’s transcriptions.

Alias for user_contributions()

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

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

Returns

dict

Genius.user_unreviewed(user_id, per_page=None, next_cursor=None, sort='popularity', text_format=None)

Gets user’s unreviewed annotations.

Alias for user_contributions()

This method gets user annotations that have the “This annotations is unreviewed” sign above them.

Parameters

  • user_id (int) – Genius user ID

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

  • next_cursor (str, optional) – Paginated offset (address of the next cursor).

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

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

Returns

dict

Video Methods

Genius.video

Gets data for a specific video.

Genius.videos

Gets the videos of an album, article or song or the featured videos.
Genius.video(video_id, text_format=None)

Gets data for a specific video.

Parameters

  • video_id (int) – Genius video ID

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

Returns

dict

Genius.videos(album_id=None, article_id=None, song_id=None, video_id=None, per_page=None, page=None, series=False)

Gets the videos of an album, article or song or the featured videos.

Parameters

  • album_id (int, optional) – Genius album ID

  • article_id (int, optional) – Genius article ID

  • song_id (int, optional) – Genius song ID

  • video_id (int, optional) – Genius video ID

  • 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).

  • series (bool, optional) – If set to True, returns episodes

  • Genius original video series that the item has been mentioned in. (of) –

Returns

dict

Note

If you specify no album, article or song, the method will return a series of videos. In this case, if series=True, the results will be the videos in the VIDEOS section on the homepage. But if series=False, the method returns another set of videos that we are not sure what they are at the moment.

Misc. Methods

Miscellaneous methods that are mostly standalones.

Genius.line_item

Gets data for a specific line item.

Genius.voters

Gets the voters of an item.
Genius.line_item(line_item_id, text_format=None)

Gets data for a specific line item.

Parameters

  • line_item_id (int) – Genius line item ID

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

Returns

dict

Warning

This method requires a logged in user and will raise NotImplementedError.

Genius.voters(annotation_id=None, answer_id=None, article_id=None, comment_id=None)

Gets the voters of an item. You must supply one of annotation_id, answer_id, article_id or comment_id.

Parameters

  • annotation_id (int, optional) – Genius annotation ID

  • answer_id (int, optional) – Genius answer ID

  • article_id (int, optional) – Genius article ID

  • comment_id (int, optional) – Genius comment ID

Returns

dict