Genius¶
The Genius class provides a high-level interface to the Genius API. This class provides convenient access to the standard API, the public API, and additional features such as downloading lyrics.
-
class
lyricsgenius.
Genius
(client_access_token, response_format='plain', timeout=5, sleep_time=0.5, verbose=True, remove_section_headers=False, skip_non_songs=True, excluded_terms=None, replace_default_terms=False)¶ Bases:
lyricsgenius.api.api.API
,lyricsgenius.api.api.PublicAPI
User-level interface with the Genius.com API and public API.
- Parameters
client_access_token (
str
) – API key provided by Genius.response_format (
str
, optional) – API response format (dom, plain, html).timeout (
int
, optional) – time before quitting on response (seconds).sleep_time (
str
, optional) – time to wait between requests.verbose (
bool
, optional) – Turn printed messages on or off.remove_section_headers (
bool
, optional) – If True, removes [Chorus], [Bridge], etc. headers from lyrics.skip_non_songs (
bool
, optional) – If True, attempts to skip non-songs (e.g. track listings).excluded_terms (
list
, optional) – extra terms for flagging results as non-lyrics.replace_default_terms (
list
, optional) – if True, replaces default excluded terms with user’s. Default excluded terms are listed below.
-
verbose
¶ Turn printed messages on or off.
- Type
bool
, optional
-
remove_section_headers
¶ If True, removes [Chorus], [Bridge], etc. headers from lyrics.
- Type
bool
, optional
-
skip_non_songs
¶ If True, attempts to skip non-songs (e.g. track listings).
- Type
bool
, optional
-
excluded_terms
¶ extra terms for flagging results as non-lyrics.
- Type
list
, optional
-
replace_default_terms
¶ if True, replaces default excluded terms with user’s.
- Type
list
, optional
- Returns
Note
Default excluded terms are the following regular expressions:
tracks?list
,album art(work)?
,liner notes
,booklet
,credits
,interview
,skit
,instrumental
, andsetlist
.
Album Methods¶
Gets data for a specific album. |
|
Gets the album charts. |
|
Gets the comments on an album page. |
|
Gets cover arts of a specific album. |
|
Gets the leaderboard of an album. |
|
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 IDtext_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 IDper_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 IDtext_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 IDper_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 IDper_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¶
Searches songs hosted on Genius. |
|
Gets the edits on annotation (its versions). |
|
Gets the comments on an annotation. |
-
Genius.
annotation
(annotation_id, text_format=None, public_api=False)¶ Searches songs hosted on Genius.
- Parameters
annotation_id (
int
) – annotation IDtext_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).public_api (
bool
, optional) – If True, performs the search using the public API endpoint.
- Returns
dict
Note
Using the public API will return the same annotation and referent but with more fields:
API: Annotation will have 19 fields and the referent 15.
Public API: Annotation will have 32 fields and referent 20.
-
Genius.
annotation_edits
(annotation_id, text_format=None)¶ Gets the edits on annotation (its versions).
- Parameters
annotation_id (
int
) – Genius annotation IDtext_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 IDper_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¶
Gets data for a specific article. |
|
Gets the comments on an article. |
|
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 IDtext_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 IDper_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 IDper_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¶
Gets data for a specific artist. |
|
Gets activities on artist’s songs. |
|
Gets artist’s albums. |
|
Gets contribution opportunities related to the artist. |
|
Gets artist’s followers. |
|
Gets artist’s top scholars. |
|
Gets artist’s songs. |
|
Saves lyrics from multiple Artist objects as JSON object. |
|
Searches artist’s songs. |
-
Genius.
artist
(artist_id, text_format=None, public_api=False)¶ Gets data for a specific artist.
- Parameters
artist_id (
int
) – Genius artist IDtext_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).public_api (
bool
, optional) – If True, performs the search using the public API endpoint.
- Returns
dict
Note
Using the public API will return the same artist but with more fields:
API: Result will have 19 fields.
Public API: Result will have 24 fields.
-
Genius.
artist_activity
(artist_id, per_page=None, page=None, text_format=None)¶ Gets activities on artist’s songs.
- Parameters
artist_id (
int
) – Genius artist IDper_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 IDper_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 IDper_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 IDper_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 IDper_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).
- Returns
dict
-
Genius.
artist_songs
(artist_id, per_page=None, page=None, sort='title', public_api=False)¶ Gets artist’s songs.
- Parameters
artist_id (
int
) – Genius artist IDsort (
str
, optional) – Sorting preference. Either based on ‘title’ or ‘popularity’.per_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).public_api (
bool
, optional) – If True, performs the search using the public API endpoint.
- Returns
dict
Note
Using the public API will return the same songs but with more fields:
API: Song will have 17 fields.
Public API: Song will have 21 fields.
-
Genius.
save_artists
(artists, filename='artist_lyrics', overwrite=False, ensure_ascii=True)¶ Saves lyrics from multiple Artist objects as JSON object.
- Parameters
artists (
list
) – List ofArtist
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 IDsearch_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¶
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
orsong_id
.- Parameters
album_id (
int
, optional) – Genius album IDsong_id (
int
, optional) – Genius song IDtext_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’). Defines the text formatting for the annotation of the cover arts, if there are any.
- Returns
dict
Discussion Methods¶
-
Genius.
discussion
(disscussion_id, text_format=None)¶ Gets data for a specific discussion.
- Parameters
disscussion_id (
int
) – Genius discussion IDtext_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
-
Genius.
discussion_replies
(disscussion_id, per_page=None, page=None, text_format=None)¶ Gets the replies on a discussion.
- Parameters
disscussion_id (
int
) – Genius discussion IDper_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
Leaderboard Methods¶
Gets the Genius community leaderboard. |
|
Gets the Genius charts. |
-
Genius.
leaderboard
(time_period='day', per_page=None, page=None, text_format=None)¶ Gets the Genius community leaderboard.
This method gets data of the community charts on the Genius.com page.
- Parameters
time_period (
str
, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).per_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
-
Genius.
charts
(time_period='day', chart_genre='all', per_page=None, page=None, text_format=None, type_='songs')¶ Gets the Genius charts.
This method gets data of the chart on the Genius.com page.
- Parameters
time_period (
str
, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).chart_genre (
str
, optional) – The genre of the results.per_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).type (
int
, optional) – The type to get the charts for. (‘songs’, ‘albums’, ‘artists’ or ‘referents’).
- Returns
dict
Note
The referents mentioned in the description of the
type_
argument is shown as Lyrics in the drop-down menu on Genius.com where you can choose the Type.
Question & Answer Methods¶
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
orsong_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¶
Gets data of one or more referents. |
|
Gets item’s referents |
|
Gets the referents (lyrics) charts. |
-
Genius.
referent
(referent_ids, text_format=None)¶ Gets data of one or more referents. This method can get multiple referents in one call, thus increasing performance.
- Parameters
referent_ids (
list
) – A list of referent IDs.text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
Note
Using this method you can get the referent itself instead of the referents of a song or webpage which is what
referents()
gets.
-
Genius.
referents
(song_id=None, web_page_id=None, created_by_id=None, per_page=None, page=None, text_format=None, public_api=False)¶ Gets item’s referents
- Parameters
song_id (
int
, optional) – song IDweb_page_id (
int
, optional) – web page IDcreated_by_id (
int
, optional) – User ID of the contributer who created the annotation(s).per_page (
int
, optional) – Number of results to return per page. It can’t be more than 50.text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).public_api (
bool
, optional) – If True, performs the search using the public API endpoint.
- Returns
dict
Note
Using the public API will return the same referents but with more fields:
API: Referent will have 15 fields.
Public API: Referent will have 20 fields.
-
Genius.
referents_charts
(time_period='day', chart_genre='all', per_page=None, page=None, text_format=None)¶ Gets the referents (lyrics) charts.
Alias for
charts()
.- Parameters
time_period (
str
, optional) – Time period of the results (‘day’, ‘week’, ‘month’ or ‘all_time’).chart_genre (
str
, optional) – The genre of the results.per_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
Search Methods¶
Searches Genius. |
|
Searches all types. |
|
Searches the albums on Genius. |
|
Searches for a specific artist and gets their songs. |
|
Searches the artists on Genius. |
|
Searches the lyrics on Genius. |
|
Searches for a specific song and gets its lyrics. |
|
Searches songs hosted on Genius. |
|
Searches the users on Genius. |
|
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 assong
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 calledtop 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 Geniusper_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 anArtist
object if the search is successful. Ifallow_name_change
is True, the name of the artist is changed to the artist name on Genius.- Parameters
artist_name (
str`|:obj:`int
) – Name of the artist to search for.(obj (max_songs) – int, optional): Maximum number of songs to search for.
sort (
str
, optional) – Sort by ‘title’ or ‘popularity’.per_page (
int
, optional) – Number of results to return per search page. It can’t be more than 50.get_full_info (
bool
, optional) – Get full info for each song (slower).allow_name_change (
bool
, optional) – If True, search attempts to switch to intended artist name.artist_id (
int
, optional) – Allows user to pass an artist ID.include_features (
bool
, optional) – If True, includes tracks featuring the artist.
- Returns
Artist object containing artist’s songs.
- Return type
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 Geniusper_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 Geniusper_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
-
Genius.
search_song
(title, artist='', get_full_info=True)¶ Searches for a specific song and gets its lyrics.
- Parameters
title (
str
) – Song title to search for.artist (
str
, optional) – Name of the artist.get_full_info (
bool
, optional) – Get full info for each song (slower).
- Returns
On success, the song object is returned, otherwise None.
- Return type
Song
|None
Tip
Set
Genius.verbose
to True to read why the search fails.Examples
genius = Genius(token) artist = genius.search_artist('Andy Shauf', max_songs=0) song = genius.search_song('Toy You', artist.name) # same as: song = genius.search_song('To You', 'Andy Shauf') print(song['lyrics'])
-
Genius.
search_songs
(search_term, per_page=None, page=None, public_api=False)¶ Searches songs hosted on Genius.
- Parameters
search_term (
str
) – A term to search on Genius.per_page (
int
, optional) – Number of results to return per page. It can’t be more than 5 for this method.page (
int
, optional) – Number of the page.public_api (
bool
, optional) – If True, performs the search using the public API endpoint.
- Returns
dict
Note
Using the API or the public API returns the same results. The only difference is in the number of values each API returns.
API: Each song has 17 fields and songs are accessable through
response['hits']
Public API: Each song has 21 fields and songs are accessible through
response['sections'][0]['hits']
-
Genius.
search_users
(search_term, per_page=None, page=None)¶ Searches the users on Genius.
Alias for
search()
- Parameters
search_term (
str
) – A term to search on Geniusper_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 Geniusper_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¶
Gets data for a specific song. |
|
Gets activities on a song. |
|
Return song’s annotations with associated fragment in list of tuple. |
|
Gets the comments on a song. |
|
Gets the contributors of a song. |
|
Uses BeautifulSoup to scrape song info off of a Genius song URL |
-
Genius.
song
(song_id, text_format=None, public_api=False)¶ Gets data for a specific song.
- Parameters
song_id (
int
) – Genius song IDtext_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).public_api (
bool
, optional) – If True, performs the search using the public API endpoint.
- Returns
dict
Note
Using the public API will return the same song but with more fields:
API: Song will have 39 fields.
Public API: Song will have 68 fields.
-
Genius.
song_activity
(song_id, per_page=None, page=None, text_format=None)¶ Gets activities on a song.
- Parameters
song_id (
int
) – Genius song IDper_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
-
Genius.
song_annotations
(song_id, text_format=None, public_api=True)¶ Return song’s annotations with associated fragment in list of tuple.
- Parameters
song_id (
int
) – song IDtext_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).public_api (
bool
, optional) – If True, performs the search using the public API endpoint.
- Returns
list of tuples(fragment, [annotations])
- Return type
list
Note
This method uses
Genius.referents()
, but provides convenient access to fragments (annotated text) and the corresponding annotations (Some fragments may have more than one annotation, because sometimes both artists and Genius users annotate them).
-
Genius.
song_comments
(song_id, per_page=None, page=None, text_format=None)¶ Gets the comments on a song.
- Parameters
song_id (
int
) – Genius song IDper_page (
int
, optional) – Number of results to return per request. It can’t be more than 50.page (
int
, optional) – Paginated offset (number of the page).text_format (
str
, optional) – Text format of the results (‘dom’, ‘html’, ‘markdown’ or ‘plain’).
- Returns
dict
-
Genius.
song_contributors
(song_id)¶ Gets the contributors of a song.
This method will return users who have contributed to this song by editing lyrics or song details.
- Parameters
song_id (
int
) – Genius song ID- Returns
dict
-
Genius.
lyrics
(urlthing)¶ Uses BeautifulSoup to scrape song info off of a Genius song URL
- Parameters
urlthing (
str
|int
) – Song ID or song URL.- Returns
str
If it can find the lyrics, otherwise None- Return type
str
|None
Note
If you pass a song ID, the method will have to make an extra request to obtain the song’s URL and scrape the lyrics off of it. So it’s best to pass the method a song’s URL.
If you want to get a song’s lyrics by searching for it, use
Genius.search_song()
instead.Note
This method removes the song headers based on the value of the
remove_section_headers
attribute.
User Methods¶
Gets data for a specific user. |
|
Gets user’s accomplishments. |
|
Gets the accounts user follows. |
|
Gets user’s followers. |
|
Gets user’s contributions. |
|
Gets user’s annotations. |
|
Gets user’s articles. |
|
Gets user’s Pyongs. |
|
Gets user’s Q&As. |
|
Gets user’s suggestions (comments). |
|
Gets user’s transcriptions. |
|
Gets user’s unreviewed annotations. |
-
Genius.
user
(user_id, text_format=None)¶ Gets data for a specific user.
- Parameters
user_id (
int
) – Genius user IDtext_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 IDper_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 IDper_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 IDper_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 IDper_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 IDper_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 IDper_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 IDper_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 IDper_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 IDper_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 IDper_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 IDper_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¶
Gets data for a specific video. |
|
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 IDtext_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 IDarticle_id (
int
, optional) – Genius article IDsong_id (
int
, optional) – Genius song IDvideo_id (
int
, optional) – Genius video IDper_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 episodesGenius 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.
Gets data for a specific line item. |
|
Gets the voters of an item. |
-
Genius.
line_item
(line_item_id, text_format=None)¶ Gets data for a specific line item.
- Parameters
line_item_id (
int
) – Genius line item IDtext_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
orcomment_id
.- Parameters
annotation_id (
int
, optional) – Genius annotation IDanswer_id (
int
, optional) – Genius answer IDarticle_id (
int
, optional) – Genius article IDcomment_id (
int
, optional) – Genius comment ID
- Returns
dict