Introduction to geniusr

Source: vignettes/intro.Rmd

The geniusr package is designed to help you retrieve data from Genius. Most of this data falls into one of two camps:

  • Details about Genius Resources (e.g. artists, songs)
  • Song lyrics hosted on Genius

Both of these areas will be introduced momentarily, once API authentication is dealt with.

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 list.

Let’s get details about the track Sing About Me, I’m Dying of Thirst by Kendrick Lamar.

get_song(song_id = 90479)
#> <Genius api.genius.com/songs/90479>
#> List of 38
#>  $ annotation_count            : int 97
#>  $ 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_state                : chr "complete"
#>  $ path                        : chr "/Kendrick-lamar-sing-about-me-im-dying-of-thirst-lyrics"
#>  $ pyongs_count                : int 128
#>  $ recording_location          : chr "TDE Red Room, Carson, CA"
#>  $ release_date                : chr "2012-10-22"
#>  $ 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 6