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

library(geniusr)

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 40
#>  $ annotation_count            : int 94
#>  $ api_path                    : chr "/songs/90479"
#>  $ apple_music_id              : chr "624345722"
#>  $ apple_music_player_url      : chr "https://genius.com/songs/90479/apple_music_player"
#>  $ 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__
#>  $ fact_track                  :List of 5
#>  $ 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/f3db37bb8953d6e671d8bb532da2e855.220x220x1.jpg"
#>  $ header_image_url            : chr "https://images.genius.com/f3db37bb8953d6e671d8bb532da2e855.220x220x1.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 138
#>  $ recording_location          : chr "TDE Red Room, Carson, CA"
#>  $ release_date                : chr "2012-10-22"
#>  $ release_date_for_display    : chr "October 22, 2012"
#>  $ song_art_image_thumbnail_url: chr "https://images.genius.com/f3db37bb8953d6e671d8bb532da2e855.220x220x1.jpg"
#>  $ song_art_image_url          : chr "https://images.genius.com/f3db37bb8953d6e671d8bb532da2e855.220x220x1.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 7
#>  $ description_annotation      :List of 15
#>  $ featured_artists            : list()
#>  $ lyrics_marked_complete_by   : NULL
#>  $ media                       :List of 3
#>  $ primary_artist              :List of 9
#>  $ producer_artists            :List of 2
#>  $ 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

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 39
#>  $ annotation_count            : int 48
#>  $ api_path                    : chr "/songs/3889"
#>  $ apple_music_id              : chr "263570790"
#>  $ apple_music_player_url      : chr "https://genius.com/songs/3889/apple_music_player"
#>  $ 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 7
#>  $ recording_location          : chr "Studio LaCoCo, Doppler Studios, Bosstown & Patchwerk Recording Studios (Atlanta)"
#>  $ 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 12
#>  $ description_annotation      :List of 15
#>  $ featured_artists            : list()
#>  $ lyrics_marked_complete_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 4

…and here’s get_song_df(), retrieving data for the same song:

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 39
#>  $ annotation_count            : int 63
#>  $ api_path                    : chr "/songs/89"
#>  $ apple_music_id              : chr "856131732"
#>  $ apple_music_player_url      : chr "https://genius.com/songs/89/apple_music_player"
#>  $ 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 349
#>  $ recording_location          : chr "D&D Studios (New York City)"
#>  $ 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 9
#>  $ 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 4
#>  $ description_annotation      :List of 15
#>  $ featured_artists            : list()
#>  $ lyrics_marked_complete_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 x 10
#>   song_id producer_artist… producer_artist… producer_artist… producer_artist…
#>     <int> <chr>            <chr>            <chr>                       <int>
#> 1      89 DJ Premier       /artists/2260    https://images.…             2260
#> # … with 5 more variables: producer_artists_image_url <chr>,
#> #   producer_artists_is_meme_verified <lgl>,
#> #   producer_artists_is_verified <lgl>, producer_artists_url <chr>,
#> #   producer_artists_iq <int>