AudD API

Introduction

AudD is music recognition API.

AudD Chrome extension is an example of our API application. It recognizes music from open tab of your browser.
The source code is available on GitHub.

You can send all the requests by GET and POST.

Required parameters

  • method — API method.
  • api_token — API token (default is "", but "" and "test" tokens allow you to make only 10 requests).

File transfer

For recognize and recognizeWithOffset methods you have to send the file for recognition. There are several parameters that you can use:

  • url — link to the file for recognition, by either GET or POST (highly recommended)
  • file — file for recognition, only by POST (recommended)
  • audio — base64 encoded file for recognition, only by POST (not recommended)

API methods

recognize is default API method. It is for standard music recognition working like Shazam. Params:

  • return — field with comma separated names of what you want to be returned. Example: timecode,lyrics,apple_music,deezer,spotify.
    Possible values: timecode (time in the recognized song when the fragment is being played), lyrics (lyrics and additional metadata, may be not really accurate), apple_music (Apple Music data and links, accurate), spotify (Spotify data and links, accurate), deezer (Deezer data and links, accurate), itunes (iTunes data and links, may be not really accurate).
  • market — a country code for Apple Music, iTunes and Spotify results. Default: us. Example: ru.

recognizeWithOffset is method for recognition by humming/singing. Method hasn't additional fields (you must only send file and specify method). It can work inaccurately.

findLyrics is method for lyrics searching. Param:

  • q — search query. Song title and artist or an excerpt from the lyrics.

Authentication and limits

For free and without api_token you can send up to 10 request per method per day.

To increase the limit and receive api_token contact us:
[email protected]
+1(302)283-9101
t.me/auddapi
vk.me/auddmusic

Error Codes

  • #901 — No api_token passed and the limit was reached (api_token)
  • #900 — Wrong API token (api_token)
  • #600 — Incorrect audio URL (url)
  • #500 — Incorrect audio file
  • #400 — Too big audio file or too big audio. 10M or 25 seconds is maximum, we recommend to record no more than 20 seconds (usually it takes less than one megabyte).
  • #300 — Neural network returned error: there was a problem with the fingerprint creation. Most likely, the audio file is too small.
  • #100 — Unknown error.

Examples of Requests

GET Music recognition with lyrics returning
https://api.audd.io/?url=https://audd.tech/example1.mp3&return=lyrics

Default music recognition

PARAMS

url
https://audd.tech/example1.mp3
return
lyrics


Sample Request
Music recognition with lyrics returning
curl --request GET \
  --url 'https://api.audd.io/?url=https://audd.tech/example1.mp3&return=lyrics'
Sample Response
{
  "status": "success",
  "result": {
    "artist": "Imagine Dragons",
    "title": "Warriors",
    "album": "Warriors",
    "release_date": "2014-09-18",
    "label": "Universal Music",
    "underground": false,
    "lyrics": {
      "song_id": "520879",
      "artist_id": "29472",
      "title": "Warriors",
      "title_with_featured": "Warriors",
      "full_title": "Warriors by Imagine Dragons",
      "artist": "Imagine Dragons",
      "lyrics": "[Verse 1]\r\n As a child, you would wait and watch from far away\r\n But you always knew that you'd be the one\r\n To work while they all play\r\n In youth, you'd lay awake at night and scheme\r\n Of all the things that you would change\r\n But it was just a dream\r\n \r\n [Chorus]\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n From dust\r\n \r\n [Verse 2]\r\n The time will come, when you will have to rise\r\n Above the best, and prove yourself\r\n Your spirit never dies\r\n Farewell, I've gone, to take my throne above\r\n But don't weep for me, 'cause this will be\r\n The labor of my love\r\n \r\n [Chorus]\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n From dust\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n From dust"
    }
  }
}
GET Recognition by humming
https://api.audd.io/recognizeWithOffset/?url=https://audd.tech/example_h1.ogg

Recognize by humming

PARAMS

url
https://audd.tech/example_h1.ogg
method
recognizeWithOffset


Sample Request
Recognition by humming
curl --request GET \
  --url 'https://api.audd.io/recognizeWithOffset/?url=https://audd.tech/example_h1.ogg'
Sample Response
{
  "status": "success",
  "result": {
    "underground": "humming",
    "humming": true,
    "count": 1,
    "list": [
      {
        "score": 0.96,
        "artist": "Taylor Swift",
        "title": "Last Christmas"
      }
    ]
  }
}
POST Music recognition with iTunes and Deezer audios returning
https://api.audd.io/

Music recognition with iTunes and Deezer audios returning. You can send all params by GET or by POST.

BODY

url
https://audd.tech/example1.mp3

Audio file URL

method
recognize

API method

return
itunes

API will return iTunes/Apple Music & Deezer data and links

itunes_country
us

Country for itunes



Sample Request
Standart music recognition with iTunes and Deezer audios returning
curl -d "method=recognize&url=https://audd.tech/example1.mp3&return=itunes&itunes_country=us" \
-X POST https://api.audd.io
Sample Response
{
  "status": "success",
  "result": {
    "artist": "Imagine Dragons",
    "title": "Warriors",
    "album": "Warriors",
    "release_date": "2014-09-18",
    "label": "Universal Music",
    "underground": false,
    "itunes": {
      "wrapperType": "track",
      "kind": "song",
      "artistId": 358714030,
      "collectionId": 1043732083,
      "trackId": 1043732102,
      "artistName": "Imagine Dragons",
      "collectionName": "Smoke + Mirrors (Deluxe)",
      "trackName": "Warriors",
      "collectionCensoredName": "Smoke + Mirrors (Deluxe)",
      "trackCensoredName": "Warriors",
      "artistViewUrl": "https://itunes.apple.com/us/artist/imagine-dragons/358714030?uo=4",
      "collectionViewUrl": "https://itunes.apple.com/us/album/warriors/1043732083?i=1043732102&uo=4",
      "trackViewUrl": "https://itunes.apple.com/us/album/warriors/1043732083?i=1043732102&uo=4",
      "previewUrl": "https://audio-ssl.itunes.apple.com/apple-assets-us-std-000001/Music3/v4/71/eb/3d/71eb3d80-78bc-55ef-2fd3-4b7c30d90765/mzaf_6715849709106549200.plus.aac.p.m4a",
      "artworkUrl30": "http://is4.mzstatic.com/image/thumb/Music62/v4/f5/8d/2f/f58d2fc8-ef23-ec96-3886-18d06e65ae6b/source/30x30bb.jpg",
      "artworkUrl60": "http://is4.mzstatic.com/image/thumb/Music62/v4/f5/8d/2f/f58d2fc8-ef23-ec96-3886-18d06e65ae6b/source/60x60bb.jpg",
      "artworkUrl100": "http://is4.mzstatic.com/image/thumb/Music62/v4/f5/8d/2f/f58d2fc8-ef23-ec96-3886-18d06e65ae6b/source/100x100bb.jpg",
      "collectionPrice": 11.99,
      "trackPrice": 1.29,
      "releaseDate": "2014-09-18T07:00:00Z",
      "collectionExplicitness": "notExplicit",
      "trackExplicitness": "notExplicit",
      "discCount": 1,
      "discNumber": 1,
      "trackCount": 21,
      "trackNumber": 18,
      "trackTimeMillis": 170799,
      "country": "USA",
      "currency": "USD",
      "primaryGenreName": "Alternative",
      "isStreamable": true
    }
  }
}
GET Adele - Hello lyrics searching
https://api.audd.io/findLyrics/?q=adele hello

Lyrics search by artist and song title

PARAMS

method
findLyrics
q
adele hello


Sample Request
Adele - Hello lyrics searching
curl --request GET \
  --url 'https://api.audd.io/findLyrics/?q=adele%20hello'
Sample Response
{
  "status": "success",
  "result": [
    {
      "song_id": "2332455",
      "artist_id": "2300",
      "title": "Hello",
      "title_with_featured": "Hello",
      "full_title": "Hello by Adele",
      "artist": "Adele",
      "lyrics": "[Verse 1]\r\n Hello, it's me\r\n I was wondering if after all these years you'd like to meet\r\n To go over everything\r\n They say that time's supposed to heal ya, but I ain't done much healing\r\n Hello, can you hear me?\r\n I'm in California dreaming about who we used to be\r\n When we were younger and free\r\n I've forgotten how it felt before the world fell at our feet\r\n There's such a difference between us\r\n And a million miles\r\n \r\n [Chorus]\r\n Hello from the other side\r\n I must've called a thousand times\r\n To tell you I'm sorry\r\n For everything that I've done\r\n But when I call, you never seem to be home\r\n Hello from the outside\r\n At least I can say that I've tried\r\n To tell you I'm sorry, for breaking your heart\r\n But it don't matter\r\n It clearly doesn't tear you apart anymore\r\n \r\n [Verse 2]\r\n Hello, how are you?\r\n It's so typical of me to talk about myself, I'm sorry\r\n I hope that you're well\r\n Did you ever make it out of that town where nothing ever happened?\r\n It's no secret that the both of us\r\n Are running out of time\r\n [Chorus]\r\n So hello from the other side\r\n I must've called a thousand times\r\n To tell you I'm sorry\r\n For everything that I've done\r\n But when I call, you never seem to be home\r\n Hello from the outside\r\n At least I can say that I've tried\r\n To tell you I'm sorry, for breaking your heart\r\n But it don't matter\r\n It clearly doesn't tear you apart anymore\r\n \r\n [Bridge]\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Ooh, anymore\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Ooh, anymore\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Ooh, anymore\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Anymore\r\n \r\n [Chorus]\r\n Hello from the other side\r\n I must've called a thousand times\r\n To tell you I'm sorry\r\n For everything that I've done\r\n But when I call, you never seem to be home\r\n Hello from the outside\r\n At least I can say that I've tried\r\n To tell you I'm sorry, for breaking your heart\r\n But it don't matter\r\n It clearly doesn't tear you apart anymore\r\n [Produced by Greg Kurstin]\r\n [Music Video]"
    }
  ]
}
GET Searching by excerpt from Radioactive lyrics
https://api.audd.io/findLyrics/?q=I'm waking up to ash and dust

Lyrics and metadata search by excerpt from the lyrics

PARAMS

method
findLyrics
q
I'm waking up to ash and dust


Sample Request
Searching by excerpt from Radioactive lyrics
curl --request GET \
  --url 'https://api.audd.io/findLyrics/?q=I%27m%20waking%20up%20to%20ash%20and%20dust'
Sample Response
{
  "status": "success",
  "result": [
    {
      "song_id": "98754",
      "artist_id": "29472",
      "title": "Radioactive",
      "title_with_featured": "Radioactive",
      "full_title": "Radioactive by Imagine Dragons",
      "artist": "Imagine Dragons",
      "lyrics": "[Verse 1]\r\n I'm waking up to ash and dust\r\n I wipe my brow and I sweat my rust\r\n I'm breathing in the chemicals\r\n \r\n [Refrain]\r\n I'm breaking in, shaping up\r\n Checking out on the prison bus\r\n This is it, the apocalypse – whoa\r\n \r\n [Pre-Chorus]\r\n I'm waking up, I feel it in my bones\r\n Enough to make my systems blow\r\n Welcome to the new age, to the new age\r\n Welcome to the new age, to the new age\r\n \r\n [Chorus]\r\n Whoa, whoa – I'm radioactive, radioactive\r\n Whoa, whoa – I'm radioactive, radioactive\r\n \r\n [Verse 2]\r\n I raise my flags, dye my clothes\r\n It's a revolution, I suppose\r\n We're painted red to fit right in, whoa\r\n \r\n [Refrain]\r\n I'm breaking in, shaping up\r\n Checking out on the prison bus\r\n This is it, the apocalypse – whoa\r\n \r\n [Pre-Chorus]\r\n I'm waking up, I feel it in my bones\r\n Enough to make my systems blow\r\n Welcome to the new age, to the new age\r\n Welcome to the new age, to the new age\r\n \r\n [Chorus]\r\n Whoa, whoa – I'm radioactive, radioactive\r\n Whoa, whoa – I'm radioactive, radioactive\r\n \r\n [Bridge]\r\n All systems go, sun hasn't died\r\n Deep in my bones, straight from inside\r\n \r\n [Pre-Chorus]\r\n I'm waking up, I feel it in my bones\r\n Enough to make my systems blow\r\n Welcome to the new age, to the new age\r\n Welcome to the new age, to the new age\r\n \r\n [Chorus]\r\n Whoa, whoa – I'm radioactive, radioactive\r\n Whoa, whoa – I'm radioactive, radioactive"
    }
  ]
}