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
(client_access_token, response_format='plain', timeout=5, sleep_time=0.5)¶ 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 theGenius
class.- 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.
-
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
- Returns
An object of the API class.
- Return type
-
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
Song details from Genius.
- Return type
dict
Examples
genius = Genius(token) song = genius.song(2857381) print(song['full_title'])
Note
This pure API method is used for fetching songs when you have their ID, and only makes a request to the API, therefore provides no lyrics. If you want the lyrics as well, use
Genius.search_song()
instead.
-
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'])
-
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’ 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).
- 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
(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']]
-
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
-
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