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

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, compress, usermeta, sources returned metadata

Examples

Only 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": "9ff43b6a-4f16-427c-93c2-92307ca505e0",
    "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": "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):

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"
      }]
    }]
  }]
}

Lookup by track ID

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

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
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):

http://api.acoustid.org/v2/lookup?client=8XaBELgH&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. However, this normally only takes a few seconds, so if your application needs to get the imported AcoustIDs back, you can use the wait parameter to wait until the submissions are imported. It is not guaranteed that the submissions will be imported on time, so your application must be able to handle the case when the submission is still in the "pending" status. You can look up the status of the pending submissions later.

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 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
wait no 1 wait up to N seconds for the submission(s) to import
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
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 asynchronous response:

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

Waiting for the results:

http://api.acoustid.org/v2/submit?client=8XaBELgH&user=XXX&wait=5&duration=641&fingerprint=XXX
{
  "status": "ok",
  "submissions": [{
    "id": 123456789,
    "status": "imported",
    "result": {
      "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0"
    }
  }]
}

Batch submission, waiting for the results and one of the submissions was not imported in time:

http://api.acoustid.org/v2/submit?client=8XaBELgH&user=XXX&wait=5&duration.0=641&fingerprint.0=XXX&duration.1=123&fingerprint.1=XXX
{
  "status": "ok",
  "submissions": [{
    "index": 0,
    "id": 123456789,
    "status": "imported",
    "result": {
      "id": "9ff43b6a-4f16-427c-93c2-92307ca505e0"
    }
  }, {
    "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

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

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
id yes 123456789 submission ID, can be used multiple times

Examples

Look up the status of two previously submitted fingerprints:

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

http://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