The geniusr package is designed to help you retrieve
data from Genius. Most of this data
falls into one of two distinct categories:
- Genius Resource (e.g. artists, songs, albums) metadata
- Song lyrics (hosted on Genius)
Functionality in both of these areas will be demonstrated once API authentication is dealt with. Make sure to read more in the docs for detailed guidance on all package features.
Authentication
geniusr data retrieval is typically done by making
authenticated requests to the Genius API. This necessitates a few
common steps:
- Create a Genius API client via the API Client management page
- Generate a client access token from your API clients page
- Pass your access token to a
GENIUS_API_TOKENenvironment variable by explicitly calling thegenius_token()function, or when prompted by other functions
Once you have set the GENIUS_API_TOKEN environment
variable, it will be active for the rest of the session and
automatically called (via genius_token()) when using
geniusr functions to request data.
Resources
The first family of data retrieval functions help with accessing data from various types of Genius Resources, explored in turn below.
Songs
Functions for requesting data on songs hosted on
Genius take the form get_song_xxx(). For example,
get_song() returns details about the song itself, as well
as user annotations that are attached to it, as a
genius_song object.
For details about the track Sing About Me, I’m Dying of Thirst by Kendrick Lamar:
get_song(song_id = 90479)
#> Sing About Me, I'm Dying of Thirst by Kendrick Lamar <api.genius.com/songs/90479>
#> List of 42
#> $ annotation_count : int 73
#> $ api_path : chr "/songs/90479"
#> $ apple_music_id : chr "624345722"
#> $ apple_music_player_url : chr "https://genius.com/songs/90479/apple_music_player"
#> $ artist_names : chr "Kendrick Lamar"
#> $ description :List of 1
#> $ embed_content : chr "<div id='rg_embed_link_90479' class='rg_embed_link' data-song-id='90479'>Read <a href='https://genius.com/Kendr"| __truncated__
#> $ featured_video : logi FALSE
#> $ full_title : chr "Sing About Me, I'm Dying of Thirst by Kendrick Lamar"
#> $ header_image_thumbnail_url : chr "https://images.genius.com/c129d5d114d2cd2303d72e073746a5db.300x300x1.jpg"
#> $ header_image_url : chr "https://images.genius.com/c129d5d114d2cd2303d72e073746a5db.1000x1000x1.jpg"
#> $ id : int 90479
#> $ lyrics_owner_id : int 121065
#> $ lyrics_placeholder_reason : NULL
#> $ lyrics_state : chr "complete"
#> $ path : chr "/Kendrick-lamar-sing-about-me-im-dying-of-thirst-lyrics"
#> $ pyongs_count : int 240
#> $ recording_location : chr "TDE Red Room, Carson, CA"
#> $ relationships_index_url : chr "https://genius.com/Kendrick-lamar-sing-about-me-im-dying-of-thirst-sample"
#> $ release_date : chr "2012-10-22"
#> $ release_date_for_display : chr "October 22, 2012"
#> $ song_art_image_thumbnail_url : chr "https://images.genius.com/c129d5d114d2cd2303d72e073746a5db.300x300x1.jpg"
#> $ song_art_image_url : chr "https://images.genius.com/c129d5d114d2cd2303d72e073746a5db.1000x1000x1.jpg"
#> $ stats :List of 9
#> $ title : chr "Sing About Me, I’m Dying of Thirst"
#> $ title_with_featured : chr "Sing About Me, I'm Dying of Thirst"
#> $ url : chr "https://genius.com/Kendrick-lamar-sing-about-me-im-dying-of-thirst-lyrics"
#> $ current_user_metadata :List of 5
#> $ album :List of 7
#> $ custom_performances :List of 10
#> $ description_annotation :List of 15
#> $ featured_artists : list()
#> $ lyrics_marked_complete_by : NULL
#> $ lyrics_marked_staff_approved_by: NULL
#> $ media :List of 3
#> $ primary_artist :List of 9
#> $ producer_artists :List of 3
#> $ song_relationships :List of 10
#> $ verified_annotations_by :List of 1
#> $ verified_contributors :List of 1
#> $ verified_lyrics_by : list()
#> $ writer_artists :List of 7Artists
Functions for requesting data on an artist (i.e. the
creator of one or more songs hosted on Genius) take the form
get_artist_xxx(). For example, get_artist()
returns details about the artist as a genius_artist
object
For info about the artist Kendrick Lamar:
get_artist(artist_id = 1421)
#> Kendrick Lamar <api.genius.com/artists/1421>
#> List of 19
#> $ alternate_names :List of 6
#> $ api_path : chr "/artists/1421"
#> $ description :List of 1
#> $ facebook_name : chr "kendricklamar"
#> $ followers_count : int 27122
#> $ header_image_url : chr "https://images.genius.com/3514a6d32afe88c48f22263e303f55d0.1000x601x1.jpg"
#> $ id : int 1421
#> $ image_url : chr "https://images.genius.com/d6d96651b423fa5a83c38ee2a4c6c939.1000x1000x1.jpg"
#> $ instagram_name : chr "kendricklamar"
#> $ is_meme_verified : logi TRUE
#> $ is_verified : logi TRUE
#> $ name : chr "Kendrick Lamar"
#> $ translation_artist : logi FALSE
#> $ twitter_name : chr "kendricklamar"
#> $ url : chr "https://genius.com/artists/Kendrick-lamar"
#> $ current_user_metadata :List of 3
#> $ iq : int 52517
#> $ description_annotation:List of 15
#> $ user :List of 11Albums
Functions for requesting data on an album take the
form get_album_xxx(). For example, get_album()
returns details about the artist as a genius_album
object.
For info on the album Good Kid, M.A.A.D City by Kendrick Lamar:
get_album(album_id = 491200)
#> good kid, m.A.A.d city (Deluxe Version) by Kendrick Lamar <api.genius.com/albums/491200>
#> List of 20
#> $ api_path : chr "/albums/491200"
#> $ comment_count : int 11
#> $ cover_art_url : chr "https://images.genius.com/1efc5de2af228d2e49d91bd0dac4dc49.1000x1000x1.jpg"
#> $ custom_header_image_url: NULL
#> $ full_title : chr "good kid, m.A.A.d city (Deluxe Version) by Kendrick Lamar"
#> $ header_image_url : chr "https://images.genius.com/1efc5de2af228d2e49d91bd0dac4dc49.1000x1000x1.jpg"
#> $ id : int 491200
#> $ lock_state : chr "super_locked"
#> $ name : chr "good kid, m.A.A.d city (Deluxe Version)"
#> $ pyongs_count : int 32
#> $ release_date : chr "2012-10-22"
#> $ release_date_components:List of 3
#> $ url : chr "https://genius.com/albums/Kendrick-lamar/Good-kid-m-a-a-d-city-deluxe-version"
#> $ current_user_metadata :List of 3
#> $ song_pageviews : int 45302868
#> $ artist :List of 9
#> $ cover_arts :List of 1
#> $ description_annotation :List of 15
#> $ performance_groups : list()
#> $ song_performances :List of 27Search
Functions for searching all content hosted on Genius
take the form search_xxx(). For example,
search_genius() returns documents matching a search term(s)
as a genius_resource object.
We can look for documents that match the search term “Compton”.
search_genius(search_term = "Compton")
#> <Genius api.genius.com/search?q=Compton>
#> List of 9
#> $ :List of 22
#> $ :List of 22
#> $ :List of 22
#> $ :List of 22
#> $ :List of 22
#> $ :List of 22
#> $ :List of 22
#> $ :List of 22
#> $ :List of 22Simplify
The functions introduced above all return fairly complex list objects
that are not immediately ready for many analytical workflows.
The get_artist|album|song() functions all have sister
functions that prepare a tibble (data frame) for you.
Here’s get_song() in action…
get_song(song_id = 3889)
#> 13th Floor/Growing Old by OutKast <api.genius.com/songs/3889>
#> List of 42
#> $ annotation_count : int 49
#> $ api_path : chr "/songs/3889"
#> $ apple_music_id : chr "263570790"
#> $ apple_music_player_url : chr "https://genius.com/songs/3889/apple_music_player"
#> $ artist_names : chr "OutKast"
#> $ description :List of 1
#> $ embed_content : chr "<div id='rg_embed_link_3889' class='rg_embed_link' data-song-id='3889'>Read <a href='https://genius.com/Outkast"| __truncated__
#> $ featured_video : logi FALSE
#> $ full_title : chr "13th Floor/Growing Old by OutKast"
#> $ header_image_thumbnail_url : chr "https://images.genius.com/d293509eb8c5aea6fb76de18a66c6b24.300x300x1.jpg"
#> $ header_image_url : chr "https://images.genius.com/d293509eb8c5aea6fb76de18a66c6b24.999x999x1.jpg"
#> $ id : int 3889
#> $ lyrics_owner_id : int 4479
#> $ lyrics_placeholder_reason : NULL
#> $ lyrics_state : chr "complete"
#> $ path : chr "/Outkast-13th-floor-growing-old-lyrics"
#> $ pyongs_count : int 9
#> $ recording_location : chr "Studio LaCoCo, Doppler Studios, Bosstown & Patchwerk Recording Studios (Atlanta)"
#> $ relationships_index_url : chr "https://genius.com/Outkast-13th-floor-growing-old-sample"
#> $ release_date : chr "1996-08-27"
#> $ release_date_for_display : chr "August 27, 1996"
#> $ song_art_image_thumbnail_url : chr "https://images.genius.com/d293509eb8c5aea6fb76de18a66c6b24.300x300x1.jpg"
#> $ song_art_image_url : chr "https://images.genius.com/d293509eb8c5aea6fb76de18a66c6b24.999x999x1.jpg"
#> $ stats :List of 8
#> $ title : chr "13th Floor/Growing Old"
#> $ title_with_featured : chr "13th Floor/Growing Old"
#> $ url : chr "https://genius.com/Outkast-13th-floor-growing-old-lyrics"
#> $ current_user_metadata :List of 5
#> $ album :List of 7
#> $ custom_performances :List of 15
#> $ description_annotation :List of 15
#> $ featured_artists : list()
#> $ lyrics_marked_complete_by : NULL
#> $ lyrics_marked_staff_approved_by: NULL
#> $ media :List of 1
#> $ primary_artist :List of 8
#> $ producer_artists :List of 1
#> $ song_relationships :List of 10
#> $ verified_annotations_by : list()
#> $ verified_contributors : list()
#> $ verified_lyrics_by : list()
#> $ writer_artists :List of 7…and here’s get_song_df(), retrieving data for the same
song:
get_song_df(song_id = 3889)
#> # A tibble: 1 × 13
#> song_id song_name song_…¹ song_…² song_…³ song_…⁴ song_…⁵ artis…⁶ artis…⁷
#> <int> <chr> <chr> <chr> <chr> <int> <int> <int> <chr>
#> 1 3889 13th Floor/Gr… https:… https:… 1996-0… 104088 49 105 OutKast
#> # … with 4 more variables: artist_url <chr>, album_id <int>, album_name <chr>,
#> # album_url <chr>, and abbreviated variable names ¹song_lyrics_url,
#> # ²song_art_image_url, ³song_release_date, ⁴song_pageviews,
#> # ⁵song_annotation_count, ⁶artist_id, ⁷artist_nameThe get_album|artist|song_df() output is a somewhat
simplified version of the get_album|artist|song()
counterpart, so make sure to check the original function objects if you
need the detail.
Furthermore, there are some tidy_xxx() functions
available to help you “un-nest” some of the data holed up in nested
lists within genius_song and genius_album
objects.
For example, tidy_song_producers() pulls out producer
credits from a genius_song() object as a tidy tibble:
song <- get_song(song_id = 89)
song
#> N.Y. State of Mind by Nas <api.genius.com/songs/89>
#> List of 42
#> $ annotation_count : int 57
#> $ api_path : chr "/songs/89"
#> $ apple_music_id : chr "856131732"
#> $ apple_music_player_url : chr "https://genius.com/songs/89/apple_music_player"
#> $ artist_names : chr "Nas"
#> $ description :List of 1
#> $ embed_content : chr "<div id='rg_embed_link_89' class='rg_embed_link' data-song-id='89'>Read <a href='https://genius.com/Nas-ny-stat"| __truncated__
#> $ featured_video : logi FALSE
#> $ full_title : chr "N.Y. State of Mind by Nas"
#> $ header_image_thumbnail_url : chr "https://images.genius.com/e6d7c852b0e01b48833efa64de26fcbe.300x300x1.jpg"
#> $ header_image_url : chr "https://images.genius.com/e6d7c852b0e01b48833efa64de26fcbe.1000x1000x1.jpg"
#> $ id : int 89
#> $ lyrics_owner_id : int 8
#> $ lyrics_placeholder_reason : NULL
#> $ lyrics_state : chr "complete"
#> $ path : chr "/Nas-ny-state-of-mind-lyrics"
#> $ pyongs_count : int 438
#> $ recording_location : chr "D&D Studios (New York City)"
#> $ relationships_index_url : chr "https://genius.com/Nas-ny-state-of-mind-sample"
#> $ release_date : chr "1994-04-19"
#> $ release_date_for_display : chr "April 19, 1994"
#> $ song_art_image_thumbnail_url : chr "https://images.genius.com/e6d7c852b0e01b48833efa64de26fcbe.300x300x1.jpg"
#> $ song_art_image_url : chr "https://images.genius.com/e6d7c852b0e01b48833efa64de26fcbe.1000x1000x1.jpg"
#> $ stats :List of 8
#> $ title : chr "N.Y. State of Mind"
#> $ title_with_featured : chr "N.Y. State of Mind"
#> $ url : chr "https://genius.com/Nas-ny-state-of-mind-lyrics"
#> $ current_user_metadata :List of 5
#> $ album :List of 7
#> $ custom_performances :List of 9
#> $ description_annotation :List of 15
#> $ featured_artists : list()
#> $ lyrics_marked_complete_by : NULL
#> $ lyrics_marked_staff_approved_by: NULL
#> $ media :List of 2
#> $ primary_artist :List of 9
#> $ producer_artists :List of 1
#> $ song_relationships :List of 10
#> $ verified_annotations_by :List of 1
#> $ verified_contributors :List of 1
#> $ verified_lyrics_by : list()
#> $ writer_artists :List of 2
tidy_song_producers(song)
#> # A tibble: 1 × 10
#> song_id producer_art…¹ produ…² produ…³ produ…⁴ produ…⁵ produ…⁶ produ…⁷ produ…⁸
#> <int> <chr> <chr> <chr> <int> <chr> <lgl> <lgl> <chr>
#> 1 89 DJ Premier /artis… https:… 2260 https:… TRUE TRUE https:…
#> # … with 1 more variable: producer_artists_iq <int>, and abbreviated variable
#> # names ¹producer_artists_name, ²producer_artists_api_path,
#> # ³producer_artists_header_image_url, ⁴producer_artists_id,
#> # ⁵producer_artists_image_url, ⁶producer_artists_is_meme_verified,
#> # ⁷producer_artists_is_verified, ⁸producer_artists_urlLyrics
There are also tools to be found in geniusr that help
with Genius lyrics retrieval. These functions take the form…you guessed
it…get_lyrics_xxx(). For example,
get_lyrics_id() finds song lyrics for a given song id, and
returns this data as a tidy tibble - each line of the track as an
observation (i.e. a row).
To complete the look, here’s song lyrics for Sing About Me, I’m Dying of Thirst:
get_lyrics_id(song_id = 90479)
#> # A tibble: 248 × 6
#> line secti…¹ secti…² song_…³ artis…⁴ song_id
#> <chr> <chr> <chr> <chr> <chr> <dbl>
#> 1 When the lights shut off and it's my… Chorus Kendri… Sing A… Kendri… 90479
#> 2 To settle down, my main concern Chorus Kendri… Sing A… Kendri… 90479
#> 3 Promise that you will sing about me Chorus Kendri… Sing A… Kendri… 90479
#> 4 Promise that you will sing about me Chorus Kendri… Sing A… Kendri… 90479
#> 5 I said when the lights shut off and … Chorus Kendri… Sing A… Kendri… 90479
#> 6 To settle down, my main concern Chorus Kendri… Sing A… Kendri… 90479
#> 7 Promise that you will sing about me Chorus Kendri… Sing A… Kendri… 90479
#> 8 Promise that you will sing about me Chorus Kendri… Sing A… Kendri… 90479
#> 9 I woke up this morning and figured I… Verse 1 Kendri… Sing A… Kendri… 90479
#> 10 In case I'm not here tomorrow Verse 1 Kendri… Sing A… Kendri… 90479
#> # … with 238 more rows, and abbreviated variable names ¹section_name,
#> # ²section_artist, ³song_name, ⁴artist_name