LyricsGenius: a Python client for the Genius.com API¶

https://travis-ci.org/johnwmillr/LyricsGenius.svg?branch=master

Genius.com is a fun website. If you aren’t familiar with it, Genius hosts a bunch of song lyrics and lets users highlight and annotate passages with interpretations, explanations, and references. Originally called RapGenius.com and devoted to lyrics from rap and hip-hop songs, the website now includes lyrics and annotations from all genres of music. You can figure out what “Words are flowing out like endless rain into a paper cup” from Across the Universe really means, or what Noname was referring to when she said “Moses wrote my name in gold and Kanye did the eulogy”.

It’s actually not too difficult to start pulling data from the Genius website. Genius is hip enough to provide a free application programming interface (API) that makes it easy for nerds to programmatically access song and artist data from their website. What the Genius API doesn’t provide, however, is a way to download the lyrics themselves. With a little help from Beautiful Soup though, it’s possible to grab the song lyrics without too much extra work. And LyricsGenius has done all of that for you already.

lyricsgenius provides a simple interface to the song, artist, and lyrics data stored on Genius.com.

Using this library you can convienently access the content on Genius.com And much more using the public API.

You can use pip to install lyricsgenius:

pip install lyricsgenius

LyricsGenius provides lots of features to work with. For example, let’s download all the lyrics of an artist’s songs, and save them to a JSON file:

from lyricsgenius import Genius

genius = Genius(token)
genius.search_artist('Andy Shauf')
artist.save_lyrics()

But before using the library you will need to get an access token. Head over to Setup to get started.

Reference¶

All public objects are documented in these sections.

API	API and PublicAPI classes
Auth	OAuth2 class
Genius	Genius class
Sender	Request sender
Types	Types
Utils	Utility functions

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(access_token, response_format='plain', timeout=5, sleep_time=0.2, retries=0)¶

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

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.
retries (int, optional) – Number of retries in case of timeouts and errors with a >= 500 response code. By default, requests are only made once.

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

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: An object of the API class.
Return type: API

Account Methods¶

API.account

Gets details about the current user.

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

Annotation Methods¶

`API.annotation`	Gets data for a specific annotation.
`API.create_annotation`	Creates an annotation for a web page.
`API.delete_annotation`	Deletes an annotation created by the authenticated user.
`API.downvote_annotation`	Downvotes an annotation.
`API.unvote_annotation`	Removes user’s vote for the annotation.
`API.upvote_annotation`	Upvotes an annotation.

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

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

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

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

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

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

Artist Methods¶

`API.artist`	Gets data for a specific artist.
`API.artist_songs`	Gets artist’s songs.

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

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

Referents Methods¶

API.referents

Gets item’s referents

API.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']]

Search Methods¶

API.search_songs

Searches songs hosted on Genius.

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

Song Methods¶

API.song

Gets data for a specific song.

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

dict

Examples

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

Web Page Methods¶

API.web_page

Gets data for a specific web page.

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

Public 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.PublicAPI(response_format='plain', timeout=5, sleep_time=0.2, retries=0, **kwargs)¶

Genius public API.

The PublicAPI class is in charge of making all the requests to the public API (genius.com/api) You can use this method without an access token since calls are made to the public API.

All methods of this class are available through the Genius class.

Parameters

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.
retries (int, optional) – Number of retries in case of timeouts and errors with a >= 500 response code. By default, requests are only made once.

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

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: An object of the PublicAPI class.
Return type: PublicAPI

Album Methods¶

`PublicAPI.album`	Gets data for a specific album.
`PublicAPI.albums_charts`	Gets the album charts.
`PublicAPI.album_comments`	Gets the comments on an album page.
`PublicAPI.album_cover_arts`	Gets cover arts of a specific album.
`PublicAPI.album_leaderboard`	Gets the leaderboard of an album.
`PublicAPI.album_tracks`	Gets the tracks of a specific album.

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

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

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

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

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

PublicAPI.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¶

`PublicAPI.annotation`	Gets data for a specific annotation.
`PublicAPI.annotation_edits`	Gets the edits on annotation (its versions).
`PublicAPI.annotation_comments`	Gets the comments on an annotation.

PublicAPI.annotation(annotation_id, text_format=None)¶

Gets data for a specific annotation.

Parameters

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

Returns

dict

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

PublicAPI.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¶

`PublicAPI.article`	Gets data for a specific article.
`PublicAPI.article_comments`	Gets the comments on an article.
`PublicAPI.latest_articles`	Gets the latest articles on the homepage.

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

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

PublicAPI.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¶

`PublicAPI.artist`	Gets data for a specific artist.
`PublicAPI.artist_activity`	Gets activities on artist’s songs.
`PublicAPI.artist_albums`	Gets artist’s albums.
`PublicAPI.artist_contribution_opportunities`	Gets contribution opportunities related to the artist.
`PublicAPI.artist_followers`	Gets artist’s followers.
`PublicAPI.artist_leaderboard`	Gets artist’s top scholars.
`PublicAPI.artist_songs`	Gets artist’s songs.
`PublicAPI.search_artist_songs`	Searches artist’s songs.

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

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

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

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

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

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

PublicAPI.artist_songs(artist_id, per_page=None, page=None, sort='popularity')¶

Gets 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).
sort (str, optional) – Sorting preference. (‘title’ or ‘popularity’)

Returns

dict

PublicAPI.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¶

PublicAPI.cover_arts

Gets the cover arts of an album or a song.

PublicAPI.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¶

`PublicAPI.discussion`	Gets data for a specific discussion.
`PublicAPI.discussions`	Gets discussions.
`PublicAPI.discussion_replies`	Gets the replies on a discussion.

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

PublicAPI.discussions(page=None)¶

Gets discussions.

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

PublicAPI.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¶

`PublicAPI.leaderboard`	Gets the Genius community leaderboard.
`PublicAPI.charts`	Gets the Genius charts.

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

PublicAPI.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¶

PublicAPI.questions

Gets the questions on an album or a song.

PublicAPI.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¶

`PublicAPI.referent`	Gets data of one or more referents.
`PublicAPI.referents`	Gets item’s referents
`PublicAPI.referents_charts`	Gets the referents (lyrics) charts.

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

PublicAPI.referents(song_id=None, web_page_id=None, created_by_id=None, per_page=None, page=None, text_format=None)¶

Gets item’s referents

You must supply song_id, web_page_id, or created_by_id.

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

PublicAPI.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¶

`PublicAPI.search`	Searches Genius.
`PublicAPI.search_all`	Searches all types.
`PublicAPI.search_albums`	Searches the albums on Genius.
`PublicAPI.search_artists`	Searches the artists on Genius.
`PublicAPI.search_lyrics`	Searches the lyrics on Genius.
`PublicAPI.search_songs`	Searches the songs on Genius.
`PublicAPI.search_users`	Searches the users on Genius.
`PublicAPI.search_videos`	Searches the videos on Genius.

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

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

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

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

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

PublicAPI.search_songs(search_term, per_page=None, page=None)¶

Searches the songs 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

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

PublicAPI.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¶

`PublicAPI.song_activity`	Gets activities on a song.
`PublicAPI.song_comments`	Gets the comments on a song.
`PublicAPI.song_contributors`	Gets the contributors of a song.

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

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

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

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

User Methods¶

`PublicAPI.user`	Gets data for a specific user.
`PublicAPI.user_accomplishments`	Gets user’s accomplishments.
`PublicAPI.user_following`	Gets the accounts user follows.
`PublicAPI.user_followers`	Gets user’s followers.
`PublicAPI.user_contributions`	Gets user’s contributions.
`PublicAPI.user_annotations`	Gets user’s annotations.
`PublicAPI.user_articles`	Gets user’s articles.
`PublicAPI.user_pyongs`	Gets user’s Pyongs.
`PublicAPI.user_questions_and_answers`	Gets user’s Q&As.
`PublicAPI.user_suggestions`	Gets user’s suggestions (comments).
`PublicAPI.user_transcriptions`	Gets user’s transcriptions.
`PublicAPI.user_unreviewed`	Gets user’s unreviewed annotations.

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

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

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

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

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

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

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

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

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

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

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

PublicAPI.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¶

`PublicAPI.video`	Gets data for a specific video.
`PublicAPI.videos`	Gets the videos of an album, article or song or the featured videos.

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

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

`PublicAPI.line_item`	Gets data for a specific line item.
`PublicAPI.voters`	Gets the voters of an item.

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

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

Auth¶

OAuth2¶

You can use this class to authenticate yourself or get URLs to redirect your users to and get them to give your Genius app the premissions you need. To find out more about how to use this class visit the Snippets.

class lyricsgenius.auth.OAuth2(client_id, redirect_uri, client_secret=None, scope=None, state=None, client_only_app=False)¶

Genius OAuth2 authorization flow.

Using this class you can authenticate a user, and get their token.

Parameters

client_id (str) – Client ID
redirect_uri (str) – Whitelisted redirect URI.
client_secret (str, optional) – Client secret.
scope (tuple | "all", optional) – Token privileges.
state (str, optional) – Request state.
client_only_app (bool, optional) – True to use the client-only authorization flow, otherwise False.

Raises

AssertionError – If neither client_secret, nor client_only_app is supplied.

property url¶

Returns the URL you redirect the user to.

You can use this property to get a URL that when opened on the user’s device, shows Genius’s authorization page where user clicks Agree to give your app access, and then Genius redirects user back to your redirect URI.

get_user_token(code=None, url=None, state=None, **kwargs)¶

Gets a user token using the url or the code parameter..

If you supply value for code, this method will use the value of the code parameter to request a token from Genius.

If you use the :method`client_only_app` and supplt the redirected URL, it will already have the token. You could pass the URL to this method or parse it yourself.

If you provide a state the method will also compare it to the initial state and will raise an exception if they’re not equal.

Parameters

code (str) – ‘code’ parameter of redirected URL.
url (str) – Redirected URL (used in client-only apps)
state (str) – state parameter of redirected URL (only provide if you want to compare with initial self.state)
**kwargs – keywords for the POST request.

Returns

User token.

Return type

str

prompt_user()¶

Prompts current user for authentication.

Opens a web browser for you to log in with Genius. Prompts to paste the URL after logging in to parse the token URL parameter.

Returns: User token.
Return type: str

classmethod client_only_app(client_id, redirect_uri, scope=None, state=None)¶

Returns an OAuth2 instance for a client-only app.

Parameters

client_id (str) – Client ID.
redirect_uri (str) – Whitelisted redirect URI.
scope (tuple | "all", optional) – Token privilages.
state (str, optional) – Request state.

Returns

OAuth2

classmethod full_code_exchange(client_id, redirect_uri, client_secret, scope=None, state=None)¶

Returns an OAuth2 instance for a full-code exchange app.

Parameters

client_id (str) – Client ID.
redirect_uri (str) – Whitelisted redirect URI.
client_secret (str) – Client secret.
scope (tuple | "all", optional) – Token privilages.
state (str, optional) – Request state.

Returns

OAuth2

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

Bases: lyricsgenius.api.api.API, lyricsgenius.api.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.

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

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

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

Sender¶

class lyricsgenius.api.base.Sender(access_token=None, response_format='plain', timeout=5, sleep_time=0.2, retries=0, public_api_constructor=False)¶

Sends requests to Genius.

_make_request(path, method='GET', params_=None, public_api=False, web=False, **kwargs)¶: Makes a request to Genius.

Types¶

Package-defined types.

Currently, the types defined here are only returned by Genius.search_album(), Genius.search_artist() and Genius.search_song().

All of the attributes listed in the types are guaranteed to be present in the returned object. To access other values that are in the response body, use to_dict().

Base¶

Base classes.

Classes¶

`Stats`	Stats of an item.
`Track`	docstring for Track

class lyricsgenius.types.Stats(json_dict)¶

Stats of an item.

Note

The values passed to this class are inconsistent, and therefore need to be set dynamically. Use the built-in dir() function to see the available attributes. You could also access the stats by the dictionary annotation. For example:

values = song.to_dict()
print(values['stats'])

class lyricsgenius.types.Track(client, json_dict, lyrics)¶

docstring for Track

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
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.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.

Album¶

An album from Genius that has the album’s songs and their lyrics.

Attributes¶

Attribute	Type
_type	`str`
api_path	`str`
artist	`Artist`
cover_art_thumbnail_url	`str`
cover_art_url	`str`
full_title	`str`
id	`int`
name	`str`
name_with_artist	`str`
release_date_components	`datetime`
tracks	`list` of `Track`
url	`str`

Methods¶

`Album.to_dict`	Converts the object to a dictionary.
`Album.to_json`	Converts the object to a json string.
`Album.to_text`	Converts song(s) lyrics to a single string.
`Album.save_lyrics`	Save Song(s) lyrics and metadata to a JSON or TXT file.

class lyricsgenius.types.Album(client, json_dict, tracks)¶

An album from the Genius.com database.

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
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.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.

Artist¶

The Artist object which holds the details of the artist and the Song objects of that artist.

Attributes¶

Attribute	Type
api_path	`str`
header_image_url	`str`
id	`int`
image_url	`str`
is_meme_verified	`bool`
is_verified	`bool`
name	`str`
songs	`list`
url	`str`

Methods¶

`Artist.song`	Gets the artist’s song.
`Artist.add_song`	Adds a song to the Artist.
`Artist.to_dict`	Converts the object to a dictionary.
`Artist.to_json`	Converts the object to a json string.
`Artist.to_text`	Converts song(s) lyrics to a single string.
`Artist.save_lyrics`	Save Song(s) lyrics and metadata to a JSON or TXT file.

class lyricsgenius.types.Artist(client, json_dict)¶

An artist with songs from the Genius.com database.

add_song(new_song, verbose=True, include_features=False)¶

Adds a song to the Artist.

This method adds a new song to the artist object. It checks if the song is already in artist’s songs and whether the song’s artist is the same as the Artist object.

Parameters

new_song (Song) – Song to be added.
verbose (bool, optional) – prints operation result.
include_features (bool, optional) – If True, includes tracks featuring the artist.

Returns

0 for success and 1 for failure.

Return type

int

Examples

genius = Genius(token)
artist = genius.search_artist('Andy Shauf', max_songs=3)

# Way 1
song = genius.search_song('To You', artist.name)
artist.add_song(song)

# Way 2
artist.add_song('To You')

song(song_name)¶

Gets the artist’s song.

If the song is in the artist’s songs, returns the song. Otherwise searches Genius for the song and then returns the song.

Parameters: song_name (str) – name of the song. the result is returned as a string.
Returns: If it can’t find the song, returns None.
Return type: Song |‌ None

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
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.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.

Song¶

This is the Song object which holds the details of the song.

Attributes¶

Attribute	Type
annotation_count	`int`
api_path	`str`
artist	`str`
full_title	`str`
header_image_thumbnail_url	`str`
header_image_url	`str`
id	`int`
lyrics	`str`
lyrics_owner_id	`int`
lyrics_state	`str`
path	`str`
primary_artist	`Artist`
pyongs_count	`int`
song_art_image_thumbnail_url	`str`
song_art_image_url	`str`
stats	`Stats`
title	`str`
title_with_featured	`str`
url	`str`

Methods¶

`Song.to_dict`	Converts the object to a dictionary.
`Song.to_json`	Converts the object to a json string.
`Song.to_text`	Converts song(s) lyrics to a single string.
`Song.save_lyrics`	Save Song(s) lyrics and metadata to a JSON or TXT file.

class lyricsgenius.types.Song(client, json_dict, lyrics='')¶

A song from the Genius.com database.

to_dict()¶: Converts the object to a dictionary.

to_json(filename=None, sanitize=True, ensure_ascii=True)¶

Converts the object to a json string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.
ensure_ascii (bool, optional) – If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped.

Returns

If filename is None, returns the lyrics as a plain string, otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

to_text(filename=None, sanitize=True)¶

Converts song(s) lyrics to a single string.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
sanitize (bool, optional) – Sanitizes the filename if True.

Returns

If filename is None, returns the lyrics as a plain string. Otherwise None.

Return type

str |‌ None

Warning

If you set sanitize to False, the file name may contain invalid characters, and therefore cause the saving to fail.

save_lyrics(filename=None, extension='json', overwrite=False, ensure_ascii=True, sanitize=True, verbose=True)¶

Save Song(s) lyrics and metadata to a JSON or TXT file.

If the extension is ‘json’ (the default), the lyrics will be saved alongside the song’s information. Take a look at the example below.

Parameters

filename (str, optional) – Output filename, a string. If not specified, the result is returned as a string.
extension (str, optional) – Format of the file (json or txt).
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.
sanitize (bool, optional) – Sanitizes the filename if True.
verbose (bool, optional) – prints operation result.

Warning

If you set sanitize to False, the file name may contain invalid characters, and thefore cause the saving to fail.

Utils¶

utility functions

lyricsgenius.utils.auth_from_environment()¶

Gets credentials from environment variables.

Uses the following env vars: GENIUS_CLIENT_ID, GENIUS_REDIRECT_URI and GENIUS_CLIENT_SECRET.

Returns: client ID, redirect URI and client secret. Replaces variables that are not present with None.
Return type: tuple

lyricsgenius.utils.clean_str(s)¶

Cleans a string to help with string comparison.

Removes punctuation and returns a stripped, NFKC normalized string in lowercase.

Parameters: s (str) – A string.
Returns: Cleaned string.
Return type: str

lyricsgenius.utils.convert_to_datetime(f)¶

Converts argument to a datetime object.

Parameters: f (str`| :obj:`dict) – string or dictionary containing date components.
Returns: datetime object.
Return type: datetime

lyricsgenius.utils.parse_redirected_url(url, flow)¶

Parse a URL for parameter ‘code’/’token’.

Parameters

url (str) – The redirect URL.
flow (str) – authorization flow (‘code’ or ‘token’)

Returns

value of ‘code’/’token’.

Return type

str

Raises

KeyError – if ‘code’/’token’ is not available or has multiple values.

lyricsgenius.utils.safe_unicode(s)¶

Encodes and decodes string based on user’s STDOUT.

Encodes string to utf-8 and then decodes it based on the user’s STDOUT’s encoding, replacing erros in the process.

Parameters: s (str) – a string.
Returns: str

lyricsgenius.utils.sanitize_filename(f)¶

Removes invalid characters from file name.

Parameters: f (str) – file name to sanitize.
Returns: sanitized file name including only alphanumeric characters, spaces, dots or underlines.
Return type: str

Release notes¶

3.0.0 (2021-02-08)¶

New¶

All requests now go through the Sender object. This provides features such as retries genius.retries and handling HTTP and timeout errors. For more info have a look at the guide about request error handling.
Added OAuth2 class to help with OAuth2 authentication.
Added PublicAPI class to allow accessing methods of the public API (genius.com/api). Check this page for a list of available methods.
Added the Album type and the genius.search_album() method.
Added the genius.tag() method to get songs by tag.
All API endpoints are now supported (e.g. upvote_annotation).
New additions to the docs.

Changed¶

GENIUS_CLIENT_ACCESS_TOKEN env var has been renamed to GENIUS_ACCESS_TOKEN.
genius.client_access_token has been renamed to genius.access_token.
genius.search_song() will also accept song_id.
Lyrics won’t be fetched for instrumental songs and their lyrics will be set to "". You can check to see if a song is instrumental using Song.instrumental.
Renamed all interface methods to remove redundant get_ (genius.get_song is now genius.song).
Renamed the lyrics method to genius.lyrics() to allow use by users. It accepts song URLs and song IDs.
Reformatted the types. Some attributes won’t be available anymore. More info on the types page.
save_lyrics() will save songs with utf8 encoding when extension='txt'.
Using Genius() will check for the env var GENIUS_ACCESS_TOKEN.

Other (CI, etc)¶

Bumped Sphinx to 3.3.0

2.0.2 (2020-09-26)¶

Added¶

Added optional ensure_ascii parameter to the following methods: Genius.save_artists, Song.save_lyrics, Song.to_json, Artist.save_lyrics and Artist.to_json

2.0.1 (2020-09-20)¶

Changed¶

Genius.lyrics()- Switched to using regular expressions to find the new_div (#154).

Setup¶

Before we start installing the package, we’ll need to get an access token.

Authorization¶

First you’ll need to sign up for a (free) account that authorizes access to the Genius API. After signing up/ logging in to your account, head out to the API section on Genius and create a new API client. After creating your client, you can generate an access token to use with the library. Genius provides two kinds of tokens:

client access token:
Mostly LyricsGenius is used to get song lyrics and song info. And this is also what the client access tokens are used for. They don’t need a user to authenticate their use (through OAuth2 or etc) and you can easily get yours by visiting the API Clients page and click on Generate Access Token. This will give you an access token, and now you’re good to go.
user token:
These tokens can do what client access tokens do and more. Using these you can get information of the account you have authenticated, create web-pages and create, manage and up-vote annotations that are hosted on your website. These tokens are really useful if you use Genius’s Web Annotator on your website. Otherwise you won’t have much need for this. Read more about user tokens on Genius’s documentation. LyricsGenius has a Auth class that provides some helpful methods to get authenticate the user and get an access token.

Installation¶

lyricsgenius requires Python 3.

Use pip to install the package from PyPI:

pip install lyricsgenius

Or, install the latest version of the package from GitHub:

pip install git+https://github.com/johnwmillr/LyricsGenius.git

Now that you have the library intalled, you can get started with using the library. See the Usage for examples.

Usage¶

Import the package and search for songs by a given artist:

from lyricsgenius import Genius

genius = Genius(token)
artist = genius.search_artist("Andy Shauf", max_songs=3, sort="title")
print(artist.songs)

Search for a single song by the same artist:

# Way 1
song = genius.search_song("To You", artist.name)

# Way 2
# this will search artist.songs first
# and if not found, uses search_song
song = artist.song("To You")

print(song.lyrics)

Add the song to the Artist object:

artist.add_song(song)
# add_song accepts song names as well:
# artist.add_song("To You")

Save the artist’s songs to a JSON file:

artist.save_lyrics()

Searching for an album and saving it:

album = genius.search_album("The Party", "Andy Shauf")
album.save_lyrics()

There are various options configurable as parameters within the Genius class:

# Turn off status messages
genius.verbose = False

# Remove section headers (e.g. [Chorus]) from lyrics when searching
genius.remove_section_headers = True

# Include hits thought to be non-songs (e.g. track lists)
genius.skip_non_songs = False

# Exclude songs with these words in their title
genius.excluded_terms = ["(Remix)", "(Live)"]

You can also call the package from the command line:

export GENIUS_ACCESS_TOKEN="my_access_token_here"
python3 -m lyricsgenius --help

Search for and save lyrics to a given song and album:

python3 -m lyricsgenius song "Begin Again" "Andy Shauf" --save
python3 -m lyricsgenius album "The Party" "Andy Shauf" --save

Search for five songs by ‘The Beatles’ and save the lyrics:

python3 -m lyricsgenius artist "The Beatles" --max-songs 5 --save

You might also like checking out the Snippets page.

Snippets¶

Here are some snippets showcasing how the library can be used.

All the songs of an artist
Artist’s least popular song
Authenticating using OAuth2
Getting song lyrics by URL or ID
Getting songs by tag (genre)
Getting the lyrics for all songs of a search
Searching for a song by lyrics
YouTube URL of artist’s songs

Getting song lyrics by URL or ID¶

genius = Genius(token)

# Using Song URL
url = "https://genius.com/Andy-shauf-begin-again-lyrics"
genius.lyrics(song_url=url)

# Using Song ID
# Requires an extra request to get song URL
id = 2885745
genius.lyrics(id)

All the songs of an artist¶

genius = Genius(token)
artist = genius.search_artist('Andy Shauf')
artist.save_lyrics()

Artist’s least popular song¶

genius = Genius(token)

artist = genius.search_artist('Andy Shauf', max_songs=1)
page = 1
songs = []
while page:
    request = genius.artist_songs(artist._id,
                                  sort='popularity',
                                  per_page=50,
                                  page=page,
                                  )
    songs.extend(request['songs'])
    page = request['next_page']
least_popular_song = genius.search_song(songs[-1]['title'], artist.name)
print(least_popular_song.lyrics)

YouTube URL of artist’s songs¶

import json
# we have saved the songs with artist.save_lyrics() before this
with open('saved_file.json') as f:
    data = json.load(f)
for song in data['songs']:
    links = song['media']
    if links:
        for media in links:
            if media['provider'] == 'youtube':
                print(print(['song'] + ': ' + media['url'])
                break

Searching for a song by lyrics¶

Using search_lyrics:

genius = Genius(token)

request = genius.search_lyrics('Jeremy can we talk a minute?')
for hit in request['sections'][0]['hits']:
    print(hit['result']['title'])

Using search_all:

genius = Genius(token)

request = genius.search_all('Jeremy can we talk a minute?')
for hit in request['sections'][2]['hits']:
    print(hit['result']['title'])

Getting songs by tag (genre)¶

Genius has the following main tags: rap, pop, r-b, rock, country, non-music To discover more tags, visit the Genius Tags page.

Genius returns 20 results per page, but it seems that it won’t return results past the 50th page if a tag has that many results. So, a popular tag like pop won’t return results for the 51st page, even though Genius probably has more than 1000 songs with the pop tag.

# this gets the lyrics of all the songs that have 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']

Getting the lyrics for all songs of a search¶

genius = Genius(token)
lyrics = []

songs = genius.search_songs('Begin Again Andy Shauf')
for song in songs['hits']:
    url = song['result']['url']
    song_lyrics = genius.lyrics(song_url=url)
    # id = song['result']['id']
    # song_lyrics = genius.lyrics(id)
    lyrics.append(song_lyrics)

Authenticating using OAuth2¶

Genius provides two flows for getting a user token: the code flow (called full code exchange) and the token flow (called client-only app). LyricsGenius provides two class methods OAuth2.full_code_exchange() and OAuth2.client_only_app() for the aforementioned flow. Visit the Authentication section in the Genius API documentation read more about the code and the token flow.

You’ll need the client ID and the redirect URI for a client-only app. For the full-code exchange you’ll also need the client secret. The package can get them for using these environment variables: GENIU_CLIENT_ID, GENIUS_REDIRECT_URI, GENIUS_CLIENT_SECRET

import lyricsgenius as lg

client_id, redirect_uri, client_secret = lg.auth_from_environment()

Authenticating yourself¶

Whitelist a redirect URI in your app’s page on Genius. Any redirect URI will work (for example http://example.com/callback)

from lyricsgenius import OAuth2, Genius

auth = OAuth2.client_only_app(
    'my_client_id',
    'my_redirect_uri',
    scope='all'
)

token = auth.prompt_user()

genius = Genius(token)

Authenticating another user¶

from lyricsgenius import OAuth2, Genius

# client-only app
auth = OAuth2.client_only_app(
    'my_client_id',
    'my_redirect_uri',
    scope='all'
)

# full code exhange app
auth = OAuth2.full_code_exchange(
    'my_client_id',
    'my_redirect_uri',
    'my_client_secret',
    scope='all',
    state='some_unique_value'
)

# this part is the same
url_for_user = auth.url
print('Redirecting you to ' + url_for_user)

# If we were using Flask:
code = request.args.get('code')
state = request.args.get('state')
token = auth.get_user_token(code, state)

genius = Genius(token)

Example projects¶

How It Works¶

LyricsGenius interfaces with Genius.com in two different ways: the authenticated developer API and the unauthenticated public API.

Developer API¶

The developer API is available through api.genius.com, and provides access to song, artist, and annotation search amongst other data sources. The endpoints within the developer API require a (free) access token. The developer API is accessed through the API class.

Public API¶

The public API can be accessed without authentication and is essentially the same service end-users access through the browser. The public API can be called at genius.com/api. These public API methods are available through the PublicAPI class.

Genius Class¶

The Genius class is a high-level interface for the content on Genius.com, inheriting from both the API and PublicAPI classes. The Genius class provides methods from the two API classes mentioned above as well as useful methods like Genius.search_song() for accessing song lyrics and more.

Lyrics¶

Genius has legal agreements with music publishers and considers the lyrics on their website to be a legal property of Genius, and won’t allow you to re-use their lyrics without explicit licensing. They even sued Google on grounds of stolen lyrics, asking for $50 million in damages, but to no avail. So it shouldn’t come as a surprise if they don’t provide lyrics in calls to the API. So how does LyricsGenius get the lyrics?

LyricsGenius uses a web-scraping library called Beautiful Soup to scrape lyrics from the song’s page on Genius. Scraping the lyrics in this way violates Genius’ terms of service. If you intend to use the lyrics for personal purposes, that shouldn’t be cause for trouble, but other than that, you should inquire what happens when you violate the terms this way. As a reminder, LyricsGenius is not responsible for your usage of the library.

Text Formatting¶

Usually, when making calls to the API, there is a text_format parameter to determine the text format of the text inside the response. LyricsGenius provides a Genius.response_format that you can set and will be used for all the calls that support a text_format parameter (not all endpoints have a text body to return so the parameter would be pointless). Let’s read what Genius docs say about text formatting:

Many API requests accept a text_format query parameter that can be used to specify how text content is formatted. The value for the parameter must be one or more of plain, html, and dom. The value returned will be an object with key-value pairs of formats and results:

plain is just plain text, no markup

html is a string of unescaped HTML suitable for rendering by a browser

dom is a nested object representing and HTML DOM hierarchy that can be used to programmatically present structured content

Now what Genius hasn’t documented is that there is one more format except the three ones above and that you can use more that one at a time. The other format is the markdown format that returns results in the Markdown format. Besides the four available formats, you can get more than one format in a call. To do this you simply set the Genius.response_format like this:

genius.response_format = 'plain,html'

Doing this will return the plain and html formats in the body of the results. Let’s give it a try:

import lyricsgenius
genius = lyricsgenius.Genius('token') # you can also set the attribute here
genius.response_format = 'plain,html'

res = genius.annotation(10225840)

# Annotation in plain formatting
print(res['annotation']['body']['plain'])

# Annotation in html formatting
print(res['annotation']['body']['html'])

You can also specify the text formatting in the call:

genius.annotation(10225840, text_format='html')

Using this will override response_format for this specific call. If you pass no text_format, the formatting will default to the response_format attribute if the method supports text formatting.

Available Formats¶

plain is just plain text, no markup
html is a string of unescaped HTML suitable for rendering by a browser
dom is a nested object representing an HTML DOM hierarchy that can be used to programmatically present structured content
markdown is text with Markdown formatting

Other Guides¶

Request Errors¶

The package will raise all HTTP and timeout erros using the HTTPError and Timeout classes of the requests package. Whenever an HTTP error is raised, proper description of the error will be printed to output. You can also access the response’s status code.

from requests.exceptions import HTTPError, Timeout
from lyricsgenius import Genius

try:
    Genius('')
except HTTPError as e:
    print(e.errno)    # status code
    print(e.args[0])  # status code
    print(e.args[1])  # error message
except Timeout:
    pass

Contributing¶

Please contribute! Genius has a lot of undocumented API endpoints. You could try to look through Genius yourself to uncover new ones, and implement them. Or you could go through the only ones that have already been implemented and try to make more sense of the parameters they take.

If you want to fix a bug, suggest improvements, or add new features to the project, just open an issue on GitHub.

If you want to run the tests on your machine before opening a PR, do the following:

cd LyricsGenius
pip install -e .[dev]

This will install the package in developer mode with all the packages necessary for running the tests. Now you can run three types of commands to test your changes:

tox -e test: runs the unit tests.
tox -e lint: runs flake8 (PEP8 for code), doc8 (PEP8 for docs) and tests creating docs.
tox: runs all tests (both of the ones above).