Genius

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

class lyricsgenius.Genius(access_token=None, response_format='plain', timeout=5, sleep_time=0.2, verbose=True, remove_section_headers=False, skip_non_songs=True, excluded_terms=None, replace_default_terms=False, retries=0, user_agent='', proxy=None)

Bases: API, PublicAPI

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

Parameters:

access_token (str, optional) – 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.
retries (int, optional) – Number of retries in case of timeouts and errors with a >= 500 response code. By default, requests are only made once.
user_agent (str, optional) – User agent for the request header.
proxy (dict[str, str], optional) – Proxy settings.

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

retries

Number of retries in case of timeouts and errors with a >= 500 response code. By default, requests are only made once.

Type:: int, 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.

Account Methods

Genius.account

Gets details about the current user.

Genius.account(text_format=None)

Gets details about the current user.

Requires scope: me.

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

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`	Gets data for a specific annotation.
`Genius.annotation_edits`	Gets the edits on annotation (its versions).
`Genius.annotation_comments`	Gets the comments on an annotation.
`Genius.create_annotation`	Creates an annotation for a web page.
`Genius.delete_annotation`	Deletes an annotation created by the authenticated user.
`Genius.downvote_annotation`	Downvotes an annotation.
`Genius.unvote_annotation`	Removes user's vote for the annotation.
`Genius.upvote_annotation`	Upvotes an annotation.

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

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

Genius.create_annotation(text, raw_annotatable_url, fragment, before_html=None, after_html=None, canonical_url=None, og_url=None, title=None, text_format=None)

Creates an annotation for a web page.

Requires scope: create_annotation.

Parameters:

text (str) – Annotation text in Markdown format.
raw_annotatable_url (str) – The original URL of the page.
fragment (str) – The highlighted fragment (the referent).
before_html (str, optional) – The HTML before the highlighted fragment (prefer up to 200 characters).
after_html (str, optional) – The HTML after the highlighted fragment (prefer up to 200 characters).
canonical_url (str, optional) – The href property of the <link rel="canonical"> tag on the page.
og_url (str, optional) – The content property of the <meta property="og:url"> tag on the page.
title (str, optional) – The title of the page.
text_format (str, optional) – Text format of the response (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns:

The annotation.

Return type:

dict

Examples

genius = Genius(token)
new = genius.update_annotation('The annotation',
'https://example.com', 'illustrative examples', title='test')
print(new['id'])

Genius.delete_annotation(annotation_id)

Deletes an annotation created by the authenticated user.

Requires scope: manage_annotation.

Parameters:: annotation_id (int) – Annotation ID.
Returns:: 204 - which is the response’s status code
Return type:: int

Genius.downvote_annotation(annotation_id, text_format=None)

Downvotes an annotation.

Requires scope: vote.

Parameters:

annotation_id (int) – Annotation ID.
text_format (str, optional) – Text format of the response (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns:

The annotation.

Return type:

dict

Genius.unvote_annotation(annotation_id, text_format=None)

Removes user’s vote for the annotation.

Requires scope: vote.

Parameters:

annotation_id (int) – Annotation ID.
text_format (str, optional) – Text format of the response (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns:

The annotation.

Return type:

dict

Genius.upvote_annotation(annotation_id, text_format=None)

Upvotes an annotation.

Requires scope: vote.

Parameters:

annotation_id (int) – Annotation ID.
text_format (str, optional) – Text format of the response (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns:

The annotation.

Return type:

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

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'])

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')

Gets artist’s songs.

Parameters:

artist_id (int) – Genius artist ID
sort (str, optional) – Sorting preference. Either based on ‘title’, ‘popularity’ or ‘release_date’.
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)

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`	Gets data for a specific discussion.
`Genius.discussions`	Gets discussions.
`Genius.discussion_replies`	Gets the replies on a discussion.

Genius.discussion(discussion_id, text_format=None)

Gets data for a specific discussion.

Parameters:

discussion_id (int) – Genius discussion ID
text_format (str, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).

Returns:

dict

Note

This request returns a 403 error and will raise NotImplementedError.

Genius.discussions(page=None)

Gets discussions.

Parameters:: page (int, optional) – Paginated offset (number of the page).
Returns:: dict

Genius.discussion_replies(discussion_id, per_page=None, page=None, text_format=None)

Gets the replies on a discussion.

Parameters:

discussion_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

Note

This request returns a 403 error and will raise NotImplementedError.

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. The default is all. (‘day’, ‘week’, ‘month’ or ‘all_time’).
chart_genre (str, optional) – The genre of the results. The default value is all. (‘all’, ‘rap’, ‘pop’, ‘rb’, ‘rock’ or ‘country’)
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. The default is songs. (‘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 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)

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 contributor 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']]

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 returns an Artist object if the search is successful.

Parameters:

artist_name (str) – 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) – Doesn’t do anything, exists to maintain backwards compatibility.
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 Artist 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=None, artist='', song_id=None, get_full_info=True)

Searches for a specific song and gets its lyrics.

You must pass either a title or a song_id.

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).
song_id (int, optional) – Song ID.

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

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

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

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:

dict

Examples

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

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

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

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(song_id=None, song_url=None, remove_section_headers=False)

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

You must supply either song_id or song_url`.

Parameters:

song_id (int, optional) – Song ID.
song_url (str, optional) – Song URL.
remove_section_headers (bool, optional) – If True, removes [Chorus], [Bridge], etc. headers from lyrics.

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 the song’s URL if it’s available.

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 Genius.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
in. (of Genius original video series that the item has been mentioned)

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.

Web Page Methods

Genius.web_page

Gets data for a specific web page.

Genius.web_page(raw_annotatable_url=None, canonical_url=None, og_url=None)

Gets data for a specific web page.

Parameters:

raw_annotatable_url (str) – The URL as it would appear in a browser.
canonical_url (str) – The URL as specified by an appropriate <link> tag in a page’s <head>.
og_url (str) – The URL as specified by an og:url <meta> tag in a page’s <head>.

Returns:

dict

Examples

genius = Genius(token)
webpage = genius.web_page('docs.genius.com')
print(webpage['full_title'])

Note

Data is only available for pages that already have at least one annotation.
You must at least pass one argument to the method.
You can pass more than one or all arguments (provided they’re the address of the same webpage).

Misc. Methods

Miscellaneous methods that are mostly standalones.

`Genius.tag`	Gets a tag's songs.
`Genius.line_item`	Gets data for a specific line item.
`Genius.voters`	Gets the voters of an item.

Genius.tag(name, page=None)

Gets a tag’s songs.

This method parses HTML to extract the hits on the page, so it’s slower than a normal API call which returns the results as JSON.

Parameters:

name (int) – Name of the tag e.g. pop or r-b. The name should be as it appears in the URL. For example, the name supplied for R&B is r-b as its URL is https://genius.com/tags/r-b.
page (int, optional) – Paginated offset (number of the page).

Returns:

A dictionary with the following keys: hits: A list of dictionaries. next_page: Either int or None.

Return type:

dict

Examples

# getting the lyrics of all the songs in the pop tag.
genius = Genius(token)
page = 1
lyrics = []
while page:
    res = genius.tag('pop', page=page)
    for hit in res['hits']:
        song_lyrics = genius.lyrics(song_url=hit['url'])
        lyrics.append(song_lyrics)
    page = res['next_page']

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