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. But if you don’t want to get an access token, you can use the methods of this class.

class lyricsgenius.PublicAPI(response_format='plain', timeout=5, sleep_time=0.5, **kwargs)¶

Bases: lyricsgenius.api.base.Sender, lyricsgenius.api.public_methods.album.AlbumMethods, lyricsgenius.api.public_methods.annotation.AnnotationMethods, lyricsgenius.api.public_methods.article.ArticleMethods, lyricsgenius.api.public_methods.artist.ArtistMethods, lyricsgenius.api.public_methods.cover_art.CoverArtMethods, lyricsgenius.api.public_methods.discussion.DiscussionMethods, lyricsgenius.api.public_methods.leaderboard.LeaderboardMethods, lyricsgenius.api.public_methods.question.QuestionMethods, lyricsgenius.api.public_methods.referent.ReferentMethods, lyricsgenius.api.public_methods.search.SearchMethods, lyricsgenius.api.public_methods.song.SongMethods, lyricsgenius.api.public_methods.user.UserMethods, lyricsgenius.api.public_methods.video.VideoMethods, lyricsgenius.api.public_methods.misc.MiscMethods

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.

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 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(disscussion_id, text_format=None)¶

Gets data for a specific discussion.

Parameters

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

Returns

dict

PublicAPI.discussion_replies(disscussion_id, per_page=None, page=None, text_format=None)¶

Gets the replies on a discussion.

Parameters

disscussion_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

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 (‘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¶

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