Skip to contents

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:

  1. Create a Genius API client via the API Client management page
  2. Generate a client access token from your API clients page
  3. Pass your access token to a GENIUS_API_TOKEN environment variable by explicitly calling the genius_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 7

Artists

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 11

Albums

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 27

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 22

Simplify

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_name

The 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_url

Lyrics

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