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 for non-commercial use only. If you would like to use the service in a commercial application, please sign up here.
- 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
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 | bnMdiXnS2Ao | 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=bnMdiXnS2Ao&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=bnMdiXnS2Ao&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=bnMdiXnS2Ao&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 | bnMdiXnS2Ao | 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=bnMdiXnS2Ao&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 | bnMdiXnS2Ao | 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=bnMdiXnS2Ao&user=XXX&duration=641&fingerprint=XXX
{
"status": "ok",
"submissions": [{
"id": 123456789,
"status": "pending"
}]
}
Batch request:
https://api.acoustid.org/v2/submit?client=bnMdiXnS2Ao&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 | bnMdiXnS2Ao | 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=bnMdiXnS2Ao&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 |