Web Service

The AcoustID web service currently supports only two operations, searching in the fingerprint database and submitting new fingerprints into the database.

Usage Guidelines

Remember that this is an open source project, with hopes to provide free and useful service. Please respect the following guidelines when integrating it into your application.

Overview

You can use both GET and POST HTTP methods to send requests to the web service, but since the audio fingerprints get fairly long, compressed POST requests are prefered.

The web service can return results in two formats, XML and JSON. If you don't specify which one you prefer, it will return JSON.

All text returned by the web service is encoded using UTF-8.

Compression

Even though compressing HTTP requests is not a common practice, our web server supports GZip-compressed bodies for HTTP POST requests. If you compress the body using GZip and set the "Content-Encoding" HTTP header to "gzip", we will decode it before parsing the parameters.

API Keys

There are two kinds of API keys used by the web service.

In order to use the web service from your application, you need to register the application. This will give you an API key that you can use in the client parameter. You can use the API key from the examples below for initial testing, but note that it will automatically expire after a few days, so don't use it in your actual application.

When submitting new fingerprints the database, you also need to provide the user API key. Every user gets this key after signing in on this website. You should not store this key in your application code, each user should provide their own.

Methods

Lookup by fingerprint

If you have an audio fingerprint generated by Chromaprint, you can use this method to lookup the MusicBrainz metadata associated with this fingerprint.

URL

https://api.acoustid.org/v2/lookup

Parameters

Name Required Values Description
format no json, jsonp, xml response format
jsoncallback no jsonAcoustidApi JSONP callback, only applicable if you select the jsonp format
client yes 0bWfeegVKAs application's API key
duration yes 641 duration of the whole audio file in seconds
fingerprint yes AQABz0qUkZ... audio fingerprint data
meta no recordings, recordingids, releases, releaseids, releasegroups, releasegroupids, tracks, compress, usermeta, sources returned metadata

Examples

Only AcoustID track IDs (default):

https://api.acoustid.org/v2/lookup?client=0bWfeegVKAs&duration=641&fingerprint=AQABz0qUkZK4oOfhL-CPc4e5C_wW2H2QH9uDL4cvoT8UNQ-eHtsE8cceeFJx-LiiHT-aPzhxoc-Opj_eI5d2hOFyMJRzfDk-QSsu7fBxqZDMHcfxPfDIoPWxv9C1o3yg44d_3Df2GJaUQeeR-cb2HfaPNsdxHj2PJnpwPMN3aPcEMzd-_MeB_Ej4D_CLP8ghHjkJv_jh_UDuQ8xnILwunPg6hF2R8HgzvLhxHVYP_ziJX0eKPnIE1UePMByDJyg7wz_6yELsB8n4oDmDa0Gv40hf6D3CE3_wH6HFaxCPUD9-hNeF5MfWEP3SCGym4-SxnXiGs0mRjEXD6fgl4LmKWrSChzzC33ge9PB3otyJMk-IVC6R8MTNwD9qKQ_CC8kPv4THzEGZS8GPI3x0iGVUxC1hRSizC5VzoamYDi-uR7iKPhGSI82PkiWeB_eHijvsaIWfBCWH5AjjCfVxZ1TQ3CvCTclGnEMfHbnZFA8pjD6KXwd__Cn-Y8e_I9cq6CR-4S9KLXqQcsxxoWh3eMxiHI6TIzyPv0M43YHz4yte-Cv-4D16Hv9F9C9SPUdyGtZRHV-OHEeeGD--BKcjVLOK_NCDXMfx44dzHEiOZ0Z44Rf6DH5R3uiPj4d_PKolJNyRJzyu4_CTD2WOvzjKH9GPb4cUP1Av9EuQd8fGCFee4JlRHi18xQh96NLxkCgfWFKOH6WGeoe4I3za4c5hTscTPEZTES1x8kE-9MQPjT8a8gh5fPgQZtqCFj9MDvp6fDx6NCd07bjx7MLR9AhtnFnQ70GjOcV0opmm4zpY3SOa7HiwdTtyHa6NC4e-HN-OfC5-OP_gLe2QDxfUCz_0w9l65HiPAz9-IaGOUA7-4MZ5CWFOlIfe4yUa6AiZGxf6w0fFxsjTOdC6Itbh4mGD63iPH9-RFy909XAMj7mC5_BvlDyO6kGTZKJxHUd4NDwuZUffw_5RMsde5CWkJAgXnDReNEaP6DTOQ65yaD88HoeX8fge-DSeHo9Qa8cTHc80I-_RoHxx_UHeBxrJw62Q34Kd7MEfpCcu6BLeB1ePw6OO4sOF_sHhmB504WWDZiEu8sKPpkcfCT9xfej0o0lr4T5yNJeOvjmu40w-TDmqHXmYgfFhFy_M7tD1o0cO_B2ms2j-ACEEQgQgAIwzTgAGmBIKIImNQAABwgQATAlhDGCCEIGIIM4BaBgwQBogEBIOESEIA8ARI5xAhxEFmAGAMCKAURKQQpQzRAAkCCBQEAKkQYIYIQQxCixCDADCABMAE0gpJIgyxhEDiCKCCIGAEIgJIQByAhFgGACCACMRQEyBAoxQiHiCBCFOECQFAIgAABR2QAgFjCDMA0AUMIoAIMChQghChASGEGeYEAIAIhgBSErnJPPEGWYAMgw05AhiiGHiBBBGGSCQcQgwRYJwhDDhgCSCSSEIQYwILoyAjAIigBFEUQK8gAYAQ5BCAAjkjCCAEEMZAUQAZQCjCCkpCgFMCCiIcVIAZZgilAQAiSHQECOcQAQIc4QClAHAjDDGkAGAMUoBgyhihgEChFCAAWEIEYwIJYwViAAlHCBIGEIEAEIQAoBwwgwiEBAEEEOoEwBY4wRwxAhBgAcKAESIQAwwIowRFhoBhAE
{
  "status": "ok",
  "results": [{
    "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0",
    "score": 1.0
  }]
}

Include MusicBrainz recording IDs (meta=recordingids):

https://api.acoustid.org/v2/lookup?client=0bWfeegVKAs&meta=recordingids&duration=641&fingerprint=AQABz0qUkZK4oOfhL-CPc4e5C_wW2H2QH9uDL4cvoT8UNQ-eHtsE8cceeFJx-LiiHT-aPzhxoc-Opj_eI5d2hOFyMJRzfDk-QSsu7fBxqZDMHcfxPfDIoPWxv9C1o3yg44d_3Df2GJaUQeeR-cb2HfaPNsdxHj2PJnpwPMN3aPcEMzd-_MeB_Ej4D_CLP8ghHjkJv_jh_UDuQ8xnILwunPg6hF2R8HgzvLhxHVYP_ziJX0eKPnIE1UePMByDJyg7wz_6yELsB8n4oDmDa0Gv40hf6D3CE3_wH6HFaxCPUD9-hNeF5MfWEP3SCGym4-SxnXiGs0mRjEXD6fgl4LmKWrSChzzC33ge9PB3otyJMk-IVC6R8MTNwD9qKQ_CC8kPv4THzEGZS8GPI3x0iGVUxC1hRSizC5VzoamYDi-uR7iKPhGSI82PkiWeB_eHijvsaIWfBCWH5AjjCfVxZ1TQ3CvCTclGnEMfHbnZFA8pjD6KXwd__Cn-Y8e_I9cq6CR-4S9KLXqQcsxxoWh3eMxiHI6TIzyPv0M43YHz4yte-Cv-4D16Hv9F9C9SPUdyGtZRHV-OHEeeGD--BKcjVLOK_NCDXMfx44dzHEiOZ0Z44Rf6DH5R3uiPj4d_PKolJNyRJzyu4_CTD2WOvzjKH9GPb4cUP1Av9EuQd8fGCFee4JlRHi18xQh96NLxkCgfWFKOH6WGeoe4I3za4c5hTscTPEZTES1x8kE-9MQPjT8a8gh5fPgQZtqCFj9MDvp6fDx6NCd07bjx7MLR9AhtnFnQ70GjOcV0opmm4zpY3SOa7HiwdTtyHa6NC4e-HN-OfC5-OP_gLe2QDxfUCz_0w9l65HiPAz9-IaGOUA7-4MZ5CWFOlIfe4yUa6AiZGxf6w0fFxsjTOdC6Itbh4mGD63iPH9-RFy909XAMj7mC5_BvlDyO6kGTZKJxHUd4NDwuZUffw_5RMsde5CWkJAgXnDReNEaP6DTOQ65yaD88HoeX8fge-DSeHo9Qa8cTHc80I-_RoHxx_UHeBxrJw62Q34Kd7MEfpCcu6BLeB1ePw6OO4sOF_sHhmB504WWDZiEu8sKPpkcfCT9xfej0o0lr4T5yNJeOvjmu40w-TDmqHXmYgfFhFy_M7tD1o0cO_B2ms2j-ACEEQgQgAIwzTgAGmBIKIImNQAABwgQATAlhDGCCEIGIIM4BaBgwQBogEBIOESEIA8ARI5xAhxEFmAGAMCKAURKQQpQzRAAkCCBQEAKkQYIYIQQxCixCDADCABMAE0gpJIgyxhEDiCKCCIGAEIgJIQByAhFgGACCACMRQEyBAoxQiHiCBCFOECQFAIgAABR2QAgFjCDMA0AUMIoAIMChQghChASGEGeYEAIAIhgBSErnJPPEGWYAMgw05AhiiGHiBBBGGSCQcQgwRYJwhDDhgCSCSSEIQYwILoyAjAIigBFEUQK8gAYAQ5BCAAjkjCCAEEMZAUQAZQCjCCkpCgFMCCiIcVIAZZgilAQAiSHQECOcQAQIc4QClAHAjDDGkAGAMUoBgyhihgEChFCAAWEIEYwIJYwViAAlHCBIGEIEAEIQAoBwwgwiEBAEEEOoEwBY4wRwxAhBgAcKAESIQAwwIowRFhoBhAE
{
  "status": "ok",
  "results": [{
    "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0",
    "score": 1.0,
    "recordings": [{
      "id": "38035858-f990-4fbb-b3b2-f2f8b958eeba"
    }]
  }]
}

And also additional metadata about the recordings from the MusicBrainz database (meta=recordings+releasegroups+compress):

https://api.acoustid.org/v2/lookup?client=0bWfeegVKAs&meta=recordings+releasegroups+compress&duration=641&fingerprint=AQABz0qUkZK4oOfhL-CPc4e5C_wW2H2QH9uDL4cvoT8UNQ-eHtsE8cceeFJx-LiiHT-aPzhxoc-Opj_eI5d2hOFyMJRzfDk-QSsu7fBxqZDMHcfxPfDIoPWxv9C1o3yg44d_3Df2GJaUQeeR-cb2HfaPNsdxHj2PJnpwPMN3aPcEMzd-_MeB_Ej4D_CLP8ghHjkJv_jh_UDuQ8xnILwunPg6hF2R8HgzvLhxHVYP_ziJX0eKPnIE1UePMByDJyg7wz_6yELsB8n4oDmDa0Gv40hf6D3CE3_wH6HFaxCPUD9-hNeF5MfWEP3SCGym4-SxnXiGs0mRjEXD6fgl4LmKWrSChzzC33ge9PB3otyJMk-IVC6R8MTNwD9qKQ_CC8kPv4THzEGZS8GPI3x0iGVUxC1hRSizC5VzoamYDi-uR7iKPhGSI82PkiWeB_eHijvsaIWfBCWH5AjjCfVxZ1TQ3CvCTclGnEMfHbnZFA8pjD6KXwd__Cn-Y8e_I9cq6CR-4S9KLXqQcsxxoWh3eMxiHI6TIzyPv0M43YHz4yte-Cv-4D16Hv9F9C9SPUdyGtZRHV-OHEeeGD--BKcjVLOK_NCDXMfx44dzHEiOZ0Z44Rf6DH5R3uiPj4d_PKolJNyRJzyu4_CTD2WOvzjKH9GPb4cUP1Av9EuQd8fGCFee4JlRHi18xQh96NLxkCgfWFKOH6WGeoe4I3za4c5hTscTPEZTES1x8kE-9MQPjT8a8gh5fPgQZtqCFj9MDvp6fDx6NCd07bjx7MLR9AhtnFnQ70GjOcV0opmm4zpY3SOa7HiwdTtyHa6NC4e-HN-OfC5-OP_gLe2QDxfUCz_0w9l65HiPAz9-IaGOUA7-4MZ5CWFOlIfe4yUa6AiZGxf6w0fFxsjTOdC6Itbh4mGD63iPH9-RFy909XAMj7mC5_BvlDyO6kGTZKJxHUd4NDwuZUffw_5RMsde5CWkJAgXnDReNEaP6DTOQ65yaD88HoeX8fge-DSeHo9Qa8cTHc80I-_RoHxx_UHeBxrJw62Q34Kd7MEfpCcu6BLeB1ePw6OO4sOF_sHhmB504WWDZiEu8sKPpkcfCT9xfej0o0lr4T5yNJeOvjmu40w-TDmqHXmYgfFhFy_M7tD1o0cO_B2ms2j-ACEEQgQgAIwzTgAGmBIKIImNQAABwgQATAlhDGCCEIGIIM4BaBgwQBogEBIOESEIA8ARI5xAhxEFmAGAMCKAURKQQpQzRAAkCCBQEAKkQYIYIQQxCixCDADCABMAE0gpJIgyxhEDiCKCCIGAEIgJIQByAhFgGACCACMRQEyBAoxQiHiCBCFOECQFAIgAABR2QAgFjCDMA0AUMIoAIMChQghChASGEGeYEAIAIhgBSErnJPPEGWYAMgw05AhiiGHiBBBGGSCQcQgwRYJwhDDhgCSCSSEIQYwILoyAjAIigBFEUQK8gAYAQ5BCAAjkjCCAEEMZAUQAZQCjCCkpCgFMCCiIcVIAZZgilAQAiSHQECOcQAQIc4QClAHAjDDGkAGAMUoBgyhihgEChFCAAWEIEYwIJYwViAAlHCBIGEIEAEIQAoBwwgwiEBAEEEOoEwBY4wRwxAhBgAcKAESIQAwwIowRFhoBhAE
{
  "status": "ok",
  "results": [{
    "score": 1.0,
    "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0",
    "recordings": [{
      "duration": 639,
      "releasegroups": [{
        "type": "Album",
        "id": "ddaa2d4d-314e-3e7c-b1d0-f6d207f5aa2f",
        "title": "Before the Dawn Heals Us"
      }],
      "title": "Lower Your Eyelids to Die With the Sun",
      "id": "cd2e7c47-16f5-46c6-a37c-a1eb7bf599ff",
      "artists": [{
        "id": "6d7b7cd4-254b-4c25-83f6-dd20f98ceacd",
        "name": "M83"
      }]
    }]
  }]
}

Lookup by track ID

You can also look up data connected to a track ID, wich is a cluster of fingerprints.

URL

https://api.acoustid.org/v2/lookup

Parameters

Name Required Values Description
format no json, jsonp, xml response format
jsoncallback no jsonAcoustidApi JSONP callback, only applicable if you select the jsonp format
client yes 0bWfeegVKAs application's API key
trackid yes 9ff43b6a-4f16-427c-93c2-92307ca505e0 track id (UUID)
meta no recordings, recordingids, releases, releaseids, releasegroups, releasegroupids, tracks, compress, usermeta, sources returned metadata

Examples

Include MusicBrainz recording IDs (meta=recordingids):

https://api.acoustid.org/v2/lookup?client=0bWfeegVKAs&meta=recordingids&trackid=9ff43b6a-4f16-427c-93c2-92307ca505e0
{
  "status": "ok",
  "results": [{
    "recordings": [{
      "id": "cd2e7c47-16f5-46c6-a37c-a1eb7bf599ff"
    }]
    "score": 1.0,
    "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0",
  }]
}

Submit

The AcoustID database depends on user-submitted content. This method can be used to submit new audio fingerprints and their corresponding metadata to the database. Multiple fingerprints can be submitted in one call.

Submissions are processed asynchronously by a background job. If you need to wait for the submission to be successfully imported, you need to do it on the client side by checking the submission status endpoint.

While you can submit a fingerprint without any metadata, it is not very useful to do so. If the file has embedded MusicBrainz tags, please send the MusicBrainz recording ID. Otherwise you can send the textual metadata.

URL

https://api.acoustid.org/v2/submit

Parameters

Name Required Values Description
format no json, xml response format
client yes 0bWfeegVKAs application's API key
clientversion no 1.0 application's version
user yes 9Hg1oNwY users's API key
duration.# yes 641 duration of the whole audio file in seconds
fingerprint.# yes AQABz0qUkZ... audio fingerprint data
bitrate.# no 192 bitrate of the audio file
fileformat.# no MP3, M4A, ... file format of the audio file
mbid.# no 4e0d8649-1f89-44f3-91af-4c0dbee81f28 corresponding MusicBrainz recording ID
track.# no High Hopes track title
artist.# no Pink Floyd track artist
album.# no The Division Bell album title
albumartist.# no Pink Floyd album artist
year.# no 1994 album release year
trackno.# no 11 track number
discno.# no 1 disc number

Examples

Standard request:

https://api.acoustid.org/v2/submit?client=0bWfeegVKAs&user=XXX&duration=641&fingerprint=XXX
{
  "status": "ok",
  "submissions": [{
    "id": 123456789,
    "status": "pending"
  }]
}

Batch request:

https://api.acoustid.org/v2/submit?client=0bWfeegVKAs&user=XXX&&duration.0=641&fingerprint.0=XXX&duration.1=123&fingerprint.1=XXX
{
  "status": "ok",
  "submissions": [{
    "index": 0,
    "id": 123456789,
    "status": "pending",
  }, {
    "index": 1,
    "id": 123456790,
    "status": "pending"
  }]
}

Get submission status

If you submitted an fingerprint and it was imported immediately, you can check the status of the submission by looking up the ID from the /v2/submit call.

URL

https://api.acoustid.org/v2/submission_status

Parameters

Name Required Values Description
format no json, xml response format
client yes 0bWfeegVKAs application's API key
clientversion no 1.0 application's version
id yes 123456789 submission ID, can be used multiple times

Examples

Look up the status of two previously submitted fingerprints:

https://api.acoustid.org/v2/submission_status?client=0bWfeegVKAs&id=123456789&id=1234567890
{
  "status": "ok",
  "submissions": [{
    "id": 123456789,
    "status": "imported",
    "result": {
      "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0"
    }
  }, {
    "id": 123456790,
    "status": "pending"
  }]
}

List AcoustIDs by MBID

URL

https://api.acoustid.org/v2/track/list_by_mbid

Parameters

Name Required Values Description
format no json, jsonp, xml response format
jsoncallback no jsonAcoustidApi JSONP callback, only applicable if you select the jsonp format
mbid yes 4e0d8649-1f89-44f3-91af-4c0dbee81f28 corresponding MusicBrainz recording ID (can be sent multiple times)
batch no 0, 1 use if you want to lookup multiple MBIDs

Software created by Lukáš Lalinský, hosted by AcoustID OÜ, data crowd-sourced by thousands of contributors.

Contact | Blog | Twitter | Facebook