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 theGenius
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
Account Methods¶
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¶
Gets data for a specific annotation. |
|
Creates an annotation for a web page. |
|
Deletes an annotation created by the authenticated user. |
|
Downvotes an annotation. |
|
Removes user’s vote for the annotation. |
|
Upvotes an annotation. |
-
API.
annotation
(annotation_id, text_format=None)¶ Gets data for a specific annotation.
- Parameters
annotation_id (
int
) – annotation IDtext_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¶
Gets data for a specific artist. |
|
Gets artist’s songs. |
-
API.
artist
(artist_id, text_format=None)¶ 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’).
- 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 IDsort (
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¶
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 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’).
- Returns
dict
Note
You may pass only one of
song_id
andweb_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¶
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¶
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 IDtext_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¶
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
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. |
-
PublicAPI.
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'])
-
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 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
-
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 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'])
-
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 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
-
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 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¶
Gets data for a specific annotation. |
|
Gets the edits on annotation (its versions). |
|
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 IDtext_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 IDtext_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 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. |
-
PublicAPI.
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
-
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 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
-
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 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. |
|
Searches artist’s songs. |
-
PublicAPI.
artist
(artist_id, text_format=None)¶ 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’).
- 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 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
-
PublicAPI.
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
-
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 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
.
-
PublicAPI.
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
-
PublicAPI.
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
-
PublicAPI.
artist_songs
(artist_id, per_page=None, page=None, sort='popularity')¶ Gets 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).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 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. |
-
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
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¶
Gets data for a specific discussion. |
|
Gets discussions. |
|
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 IDtext_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 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
Note
This request returns a 403 error and will raise
NotImplementedError
.
Leaderboard Methods¶
Gets the Genius community leaderboard. |
|
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 isall
. (‘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 issongs
. (‘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¶
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
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. |
-
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
, orcreated_by_id
.- 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’).
- 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¶
Searches Genius. |
|
Searches all types. |
|
Searches the albums on Genius. |
|
Searches the artists on Genius. |
|
Searches the lyrics on Genius. |
|
Searches the songs on Genius. |
|
Searches the users on Genius. |
|
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 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.
-
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 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
-
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 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
-
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 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
-
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 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
-
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 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
-
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 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 activities on a song. |
|
Gets the comments on a song. |
|
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 IDtext_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 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
-
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 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
-
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¶
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. |
-
PublicAPI.
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
-
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 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
-
PublicAPI.
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
-
PublicAPI.
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
-
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 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.
-
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 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
-
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 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
-
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 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
-
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 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
-
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 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
-
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 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
-
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 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. |
-
PublicAPI.
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
-
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 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. |
-
PublicAPI.
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
.
-
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
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