Acoustid

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.

  • No commercial usage — This service is provided for free to non-commercial users. If you would like to use it in a commercial application or if you are not sure whether you qualify as a non-commercial user, please contact us first.
  • Rate limiting — Do not make more than 3 requests per second.
  • Don't do anything illegal — Don't use this service in connection with any illegal products or services.
  • Let us know — If you are deploying an application that you expect to generate significant traffic to this service, please let us know in advance.

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

Note that there are two kinds of API keys required 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 please don't use it in an 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

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

URL

http://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 8XaBELgH 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, puids, compress, usermeta, sources returned metadata

Examples

Only internal Acoustid track IDs (default):

http://api.acoustid.org/v2/lookup?client=8XaBELgH&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": 112686,
    "score": 1.0
  }]
}

Include MusicBrainz recording IDs (meta=recordingids):

http://api.acoustid.org/v2/lookup?client=8XaBELgH&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": 112686,
    "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):

http://api.acoustid.org/v2/lookup?client=8XaBELgH&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"
      }]
    }]
  }]
}

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. The submission will be later processed by a background job and imported into the main database, making it available the lookup method. Multiple fingerprints can be submitted in one call.

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 track ID. Otherwise you can send the PUID or textual metadata.

URL

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

Parameters

Name Required Values Description
format no json, xml response format
client yes 8XaBELgH 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 track ID
puid.# no 4c986c91-40e5-d2b2-531e-e77ad4309691 corresponding PUID
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

List AcoustIDs by MBID

URL

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

Parameters

Name Required Values Description
format no json, 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

List AcoustIDs by PUID

URL

http://api.acoustid.org/v2/track/list_by_puid

Parameters

Name Required Values Description
format no json, xml response format
jsoncallback no jsonAcoustidApi JSONP callback, only applicable if you select the jsonp format
puid yes 4c986c91-40e5-d2b2-531e-e77ad4309691 corresponding PUID