# Genius

> Search Genius for songs and read what its contributors know about them: credits, release dates, streaming links, artist profiles, and the annotations behind the lyrics.

App · Music & Podcasts · 9 actions. Web page: https://docs.lodol.com/docs/integrations/genius

## Actions

### Find a song

Look up one song in full from its title and artist: its description, album, producers, writers, and streaming links, without needing its Genius ID first.

**Inputs**

- Song and artist (`query`, text, required): The song to find. Including the artist makes the match far more reliable.

**Outputs**

- `found` (true/false): Whether Genius matched the search to a song
- `song` (object): The best match, in full. Empty when nothing matched.

**Example output**

```json
{
  "found": true,
  "song": {
    "album_id": 344741,
    "album_name": "DAMN.",
    "annotation_count": 34,
    "artist_id": 1421,
    "artist_name": "Kendrick Lamar",
    "description": "'HUMBLE.' was the second single from Kendrick Lamar's fourth studio album, DAMN.",
    "featured_artists": [],
    "full_title": "HUMBLE. by Kendrick Lamar",
    "has_lyrics": true,
    "hot": false,
    "id": 3039923,
    "image_url": "https://images.genius.com/humble.1000x1000x1.jpg",
    "media": [
      {
        "provider": "spotify",
        "type": "audio",
        "url": "https://open.spotify.com/track/7KXjTSCq5nL1LoYtL7XAwS"
      }
    ],
    "pageviews": 8419273,
    "producer_artists": [
      {
        "id": 15452,
        "name": "Mike WiLL Made-It"
      }
    ],
    "recording_location": "",
    "release_date": "2017-03-30",
    "title": "HUMBLE.",
    "url": "https://genius.com/Kendrick-lamar-humble-lyrics",
    "writer_artists": [
      {
        "id": 1421,
        "name": "Kendrick Lamar"
      }
    ]
  }
}
```

### Get a song

Look up one song by its Genius ID: its description, album, producers, writers, streaming links, and how many people have read its page.

**Inputs**

- Song (`song_id`, number, required): The song's Genius ID, a number. Search songs, Find a song, and Get an artist's songs all return it. At least 1.

**Outputs**

- `album_id` (number): The album's Genius ID
- `album_name` (text): The album it appears on
- `annotation_count` (number): How many lyrics on the song have been annotated
- `artist_id` (number): The Genius ID of the song's primary artist
- `artist_name` (text): Everyone credited on the song, featured artists included
- `description` (text): What Genius contributors have written about the song, as plain text
- `featured_artists` (list): The artists featured on the track
- `full_title` (text): The title with the artist, as Genius displays it
- `has_lyrics` (true/false): Whether Genius holds the song's complete lyrics
- `hot` (true/false): Whether Genius is trending the song
- `id` (number): The song's Genius ID
- `image_url` (text): Link to the song's cover art
- `media` (list): Where the song can be played or bought
- `pageviews` (number): How many times the song's Genius page has been viewed
- `producer_artists` (list): Who produced it
- `recording_location` (text): Where it was recorded, when known
- `release_date` (text): When it was released, as YYYY-MM-DD. Older songs Genius only knows the year or month for are shortened to YYYY or YYYY-MM, and an unknown date is empty.
- `title` (text): The song's title
- `url` (text): Link to the song's Genius page
- `writer_artists` (list): Who is credited with writing it

**Example output**

```json
{
  "album_id": 344741,
  "album_name": "DAMN.",
  "annotation_count": 34,
  "artist_id": 1421,
  "artist_name": "Kendrick Lamar",
  "description": "'HUMBLE.' was the second single from Kendrick Lamar's fourth studio album, DAMN.",
  "featured_artists": [],
  "full_title": "HUMBLE. by Kendrick Lamar",
  "has_lyrics": true,
  "hot": false,
  "id": 3039923,
  "image_url": "https://images.genius.com/humble.1000x1000x1.jpg",
  "media": [
    {
      "provider": "spotify",
      "type": "audio",
      "url": "https://open.spotify.com/track/7KXjTSCq5nL1LoYtL7XAwS"
    }
  ],
  "pageviews": 8419273,
  "producer_artists": [
    {
      "id": 15452,
      "name": "Mike WiLL Made-It"
    }
  ],
  "recording_location": "",
  "release_date": "2017-03-30",
  "title": "HUMBLE.",
  "url": "https://genius.com/Kendrick-lamar-humble-lyrics",
  "writer_artists": [
    {
      "id": 1421,
      "name": "Kendrick Lamar"
    }
  ]
}
```

### Get a song's annotations

Read what Genius contributors have written about a song's lyrics: each annotated line and the explanation attached to it.

**Inputs**

- Song (`song_id`, number, required): The song's Genius ID, a number. Search songs, Find a song, and Get an artist's songs all return it. At least 1.
- How many results (`limit`, number): How many results to return, from 1 to 50. From 1 to 50. Default: `20`.
- Page (`page`, number): Which page of results to read. Starts at 1. Read the next page to keep going past the first batch. From 1 to 1000. Default: `1`.

**Outputs**

- `annotations` (list): The song's annotated lyrics, in song order
- `result_count` (number): How many annotations this page returned

**Example output**

```json
{
  "annotations": [
    {
      "authors": [
        "ewokABdevito"
      ],
      "body": "Kendrick flips the beat's minimal piano line into a warning about chasing status.",
      "comment_count": 7,
      "fragment": "Hol' up, lil' bitch, hol' up",
      "id": 13029842,
      "referent_id": 13029842,
      "referent_url": "https://genius.com/13029842",
      "state": "accepted",
      "url": "https://genius.com/13029842",
      "verified": false,
      "votes_total": 412
    }
  ],
  "result_count": 1
}
```

### Get a web page's annotations

Read the annotations Genius users have left on any web page from its URL alone: an article, an essay, or a transcript.

**Inputs**

- Page URL (`url`, text, required): The full URL of the annotated page.
- How many results (`limit`, number): How many results to return, from 1 to 50. From 1 to 50. Default: `20`.
- Page (`page`, number): Which page of results to read. Starts at 1. Read the next page to keep going past the first batch. From 1 to 1000. Default: `1`.

**Outputs**

- `annotations` (list): The annotations left on the page
- `found` (true/false): Whether Genius holds a record for the page
- `result_count` (number): How many annotations this page returned
- `web_page` (object): The page's Genius record, or empty when it has none

**Example output**

```json
{
  "annotations": [
    {
      "authors": [
        "ewokABdevito"
      ],
      "body": "Kendrick flips the beat's minimal piano line into a warning about chasing status.",
      "comment_count": 7,
      "fragment": "Hol' up, lil' bitch, hol' up",
      "id": 13029842,
      "referent_id": 13029842,
      "referent_url": "https://genius.com/13029842",
      "state": "accepted",
      "url": "https://genius.com/13029842",
      "verified": false,
      "votes_total": 412
    }
  ],
  "found": true,
  "result_count": 1,
  "web_page": {
    "annotation_count": 3,
    "canonical_url": "https://docs.genius.com",
    "domain": "docs.genius.com",
    "id": 10347,
    "normalized_url": "docs.genius.com",
    "share_url": "https://genius.com/Genius-api-documentation-annotated",
    "title": "Genius API",
    "url": "https://docs.genius.com"
  }
}
```

### Get an annotation

Look up one annotation by its Genius ID, along with the lyric it explains, its score, and who wrote it.

**Inputs**

- Annotation (`annotation_id`, number, required): The annotation's Genius ID, a number. The annotation actions return it. At least 1.

**Outputs**

- `authors` (list): The Genius contributors who wrote it
- `body` (text): What the annotation says, as plain text
- `comment_count` (number): How many comments have been left on it
- `fragment` (text): The lyric or passage the annotation explains
- `id` (number): The annotation's Genius ID
- `referent_id` (number): The Genius ID of the annotated fragment
- `referent_url` (text): Link to the annotated fragment on Genius
- `state` (text): Where it stands on Genius: 'accepted', 'verified', 'pending', or 'needs_exegesis'
- `url` (text): Link to the annotation on Genius
- `verified` (true/false): Whether the artist themselves verified the annotation
- `votes_total` (number): The annotation's score: upvotes minus downvotes

**Example output**

```json
{
  "authors": [
    "ewokABdevito"
  ],
  "body": "Kendrick flips the beat's minimal piano line into a warning about chasing status.",
  "comment_count": 7,
  "fragment": "Hol' up, lil' bitch, hol' up",
  "id": 13029842,
  "referent_id": 13029842,
  "referent_url": "https://genius.com/13029842",
  "state": "accepted",
  "url": "https://genius.com/13029842",
  "verified": false,
  "votes_total": 412
}
```

### Get an artist

Look up an artist's Genius profile: their biography, follower count, social handles, images, and whether Genius has verified them.

**Inputs**

- Artist (`artist_id`, number, required): The artist's Genius ID, a number. Every song result carries the ID of its artist. At least 1.

**Outputs**

- `alternate_names` (list): Other names they record or are credited under
- `description` (text): The biography Genius contributors have written, as plain text
- `facebook_name` (text): Their Facebook username, when listed
- `followers_count` (number): How many Genius users follow them
- `header_image_url` (text): Link to the banner on their Genius page
- `id` (number): The artist's Genius ID
- `image_url` (text): Link to the artist's photo
- `instagram_name` (text): Their Instagram handle, when listed
- `is_verified` (true/false): Whether the artist has claimed the page on Genius
- `name` (text): The artist's name
- `twitter_name` (text): Their X (Twitter) handle, when listed
- `url` (text): Link to the artist's Genius page

**Example output**

```json
{
  "alternate_names": [
    "K.Dot",
    "Kung Fu Kenny"
  ],
  "description": "Kendrick Lamar Duckworth is a rapper from Compton, California.",
  "facebook_name": "kendricklamar",
  "followers_count": 41827,
  "header_image_url": "https://images.genius.com/kendrick-header.jpg",
  "id": 1421,
  "image_url": "https://images.genius.com/kendrick.1000x1000x1.jpg",
  "instagram_name": "kendricklamar",
  "is_verified": true,
  "name": "Kendrick Lamar",
  "twitter_name": "kendricklamar",
  "url": "https://genius.com/artists/Kendrick-lamar"
}
```

### Get an artist's songs

List the songs Genius credits to an artist, ordered by popularity, title, or release date.

**Inputs**

- Artist (`artist_id`, number, required): The artist's Genius ID, a number. Every song result carries the ID of its artist. At least 1.
- Order by (`sort`, text): How to order the songs. One of: `popularity` (Most popular first), `title` (Title (A-Z)), `release_date` (Release date). Default: `popularity`.
- How many results (`limit`, number): How many results to return, from 1 to 50. From 1 to 50. Default: `20`.
- Page (`page`, number): Which page of results to read. Starts at 1. Read the next page to keep going past the first batch. From 1 to 1000. Default: `1`.

**Outputs**

- `next_page` (number): The page number to ask for next. Empty on the last page, which is how a paging loop knows to stop.
- `songs` (list): The artist's songs, in the order asked for

**Example output**

```json
{
  "next_page": 2,
  "songs": [
    {
      "annotation_count": 34,
      "artist_id": 1421,
      "artist_name": "Kendrick Lamar",
      "full_title": "HUMBLE. by Kendrick Lamar",
      "has_lyrics": true,
      "id": 3039923,
      "image_url": "https://images.genius.com/humble.1000x1000x1.jpg",
      "pageviews": 8419273,
      "release_date": "2017-03-30",
      "title": "HUMBLE.",
      "url": "https://genius.com/Kendrick-lamar-humble-lyrics"
    }
  ]
}
```

### Look up a web page

Check whether Genius holds a record for any web page, by URL, and see how many annotations it has.

**Inputs**

- Page URL (`url`, text, required): The full URL of the page to look up.

**Outputs**

- `found` (true/false): Whether Genius holds a record for the page
- `web_page` (object): The page's Genius record, or empty when it has none

**Example output**

```json
{
  "found": true,
  "web_page": {
    "annotation_count": 3,
    "canonical_url": "https://docs.genius.com",
    "domain": "docs.genius.com",
    "id": 10347,
    "normalized_url": "docs.genius.com",
    "share_url": "https://genius.com/Genius-api-documentation-annotated",
    "title": "Genius API",
    "url": "https://docs.genius.com"
  }
}
```

### Search songs

Search Genius for songs by title, artist, or a line of lyrics, and get the ID, artist, release date, and cover art of each match.

**Inputs**

- Search terms (`query`, text, required): What to look for: a song title, an artist, or a line of lyrics.
- How many results (`limit`, number): How many results to return, from 1 to 20. From 1 to 20. Default: `10`.
- Page (`page`, number): Which page of results to read. Starts at 1. Read the next page to keep going past the first batch. From 1 to 1000. Default: `1`.

**Outputs**

- `result_count` (number): How many songs this page returned
- `songs` (list): The matching songs, best match first

**Example output**

```json
{
  "result_count": 1,
  "songs": [
    {
      "annotation_count": 34,
      "artist_id": 1421,
      "artist_name": "Kendrick Lamar",
      "full_title": "HUMBLE. by Kendrick Lamar",
      "has_lyrics": true,
      "id": 3039923,
      "image_url": "https://images.genius.com/humble.1000x1000x1.jpg",
      "pageviews": 8419273,
      "release_date": "2017-03-30",
      "title": "HUMBLE.",
      "url": "https://genius.com/Kendrick-lamar-humble-lyrics"
    }
  ]
}
```