Web API

The AcousticBrainz server provides a Web API for getting and submitting data.

Base URL: https://acousticbrainz.org

Endpoint Reference

Core data

GET /api/v1/high-level

Get high-level data for many recordings at once.

Example response:

{"mbid1": {"offset1": {document},
           "offset2": {document}},
 "mbid2": {"offset1": {document}}
}

MBIDs and offset keys are returned as strings (as per JSON encoding rules). If an offset is not specified in the request for an mbid or is not a valid integer >=0, the offset will be 0. MBID keys are always lower-case, even if the provided recording MBIDs are upper-case or mixed case.

If the list of MBIDs in the query string has a recording which is not present in the database, then it is silently ignored and will not appear in the returned data.

Query Parameters:
 
  • recording_ids

    Required. A list of recording MBIDs to retrieve

    Takes the form mbid[:offset];mbid[:offset]. Offsets are optional, and should be >= 0

    You can specify up to MAX_ITEMS_PER_BULK_REQUEST MBIDs in a request.

  • map_classesOptional. If set to ‘true’, map class names to human-readable values
Response Headers:
 
GET /api/v1/low-level

Get low-level data for many recordings at once.

Example response:

{"mbid1": {"offset1": {document},
           "offset2": {document}},
 "mbid2": {"offset1": {document}}
}

MBIDs and offset keys are returned as strings (as per JSON encoding rules). If an offset is not specified in the request for an MBID or is not a valid integer >=0, the offset will be 0. MBID keys are always lower-case, even if the provided recording MBIDs are upper-case or mixed case.

If the list of MBIDs in the query string has a recording which is not present in the database, then it is silently ignored and will not appear in the returned data.

Query Parameters:
 
  • recording_ids

    Required. A list of recording MBIDs to retrieve

    Takes the form mbid[:offset];mbid[:offset]. Offsets are optional, and should be >= 0

    You can specify up to MAX_ITEMS_PER_BULK_REQUEST MBIDs in a request.

Response Headers:
 
GET /api/v1/count

Get low-level count for many recordings at once. MBIDs not found in the database are omitted in the response.

Example response:

{"mbid1": {"count": 3},
 "mbid2": {"count": 1}
}

MBID keys are always lower-case, even if the provided recording MBIDs are upper-case or mixed case.

Query Parameters:
 
  • recording_ids

    Required. A list of recording MBIDs to retrieve

    Takes the form mbid;mbid.

You can specify up to MAX_ITEMS_PER_BULK_REQUEST MBIDs in a request.

Response Headers:
 
GET /api/v1/(uuid: mbid)/high-level

Get high-level data for recording with a given MBID.

This endpoint returns one document at a time. If there are many submissions for an MBID, you can browse through them by specifying an offset parameter n. Documents are sorted by the submission time of their associated low-level documents.

You can get the total number of low-level submissions using /<mbid>/count endpoint.

Query Parameters:
 
  • nOptional. Integer specifying an offset for a document.
  • map_classesOptional. If set to ‘true’, map class names to human-readable values
Response Headers:
 
GET /api/v1/(uuid: mbid)/low-level

Get low-level data for a recording with a given MBID.

This endpoint returns one document at a time. If there are many submissions for an MBID, you can browse through them by specifying an offset parameter n. Documents are sorted by their submission time.

You can the get total number of low-level submissions using the /<mbid>/count endpoint.

Query Parameters:
 
  • nOptional. Integer specifying an offset for a document.
Response Headers:
 
POST /api/v1/(uuid: mbid)/low-level

Submit low-level data to AcousticBrainz.

Request Headers:
 
Response Headers:
 
GET /api/v1/(uuid: mbid)/count

Get the number of low-level data submissions for a recording with a given MBID.

Example response:

{
    "mbid": mbid,
    "count": n
}

MBID values are always lower-case, even if the provided recording MBID is upper-case or mixed case.

Response Headers:
 

Datasets

POST /api/v1/datasets/

Create a new dataset.

Example request:

{
    "name": "Mood",
    "description": "Dataset for mood classification.",
    "public": true,
    "classes": [
        {
            "name": "Happy",
            "description": "Recordings that represent happiness.",
            "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
        },
        {
            "name": "Sad"
        }
    ]
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Name of the dataset.
  • description (string) – Optional. Description of the dataset.
  • public (boolean) – Optional. true to make dataset public, false to make it private. New datasets are public by default.
  • classes (array) –

    Optional. Array of objects containing information about classes to add into new dataset. For example:

    {
        "name": "Happy",
        "description": "Recordings that represent happiness.",
        "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
    }
    
Response Headers:
 
Response JSON Object:
 
  • success (boolean) – True on successful creation.
  • dataset_id (string) – ID (UUID) of newly created dataset.
PUT /api/v1/datasets/(uuid: dataset_id)/recordings

Add recordings to a class in a dataset.

Example request:

{
    "class_name": "Happy",
    "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
}
Request Headers:
 
Request JSON Object:
 
  • class_name (string) – Required. Name of the class.
  • recordings (array) – Required. Array of recoding MBIDs (string) to add into that class.
Response Headers:
 
DELETE /api/v1/datasets/(uuid: dataset_id)/recordings

Delete recordings from a class in a dataset.

Example request:

{
    "class_name": "Happy",
    "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
}
Request Headers:
 
Request JSON Object:
 
  • class_name (string) – Required. Name of the class.
  • recordings (array) – Required. Array of recoding MBIDs (string) that need be deleted from a class.
Response Headers:
 
POST /api/v1/datasets/(uuid: dataset_id)/classes

Add a class to a dataset.

The data can include an optional list of recording ids. If these are included, the recordings are also added to the list. Duplicate recording ids are ignored.

If a class with the given name already exists, the recordings (if provided) will be added to the existing class.

Example request:

{
    "name": "Not Mood",
    "description": "Dataset for mood misclassification.",
    "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Name of the class. Must be unique within a dataset.
  • description (string) – Optional. Description of the class.
  • recordings (array) – Optional. Array of recording MBIDs (string) to add into that class. For example: ["770cc467-8dde-4d22-bc4c-a42f91e"].
Response Headers:
 
PUT /api/v1/datasets/(uuid: dataset_id)/classes

Update class in a dataset.

If one of the fields is not specified, it will not be updated.

Example request:

{
    "name": "Very happy",
    "new_name": "Recordings that represent ultimate happiness."
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Current name of the class.
  • new_name (string) – Optional. New name of the class. Must be unique within a dataset.
  • description (string) – Optional. Description of the class.
Response Headers:
 
DELETE /api/v1/datasets/(uuid: dataset_id)/classes

Delete class and all of its recordings from a dataset.

Example request:

{
    "name": "Sad"
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Name of the class.
Response Headers:
 
GET /api/v1/datasets/(uuid: dataset_id)

Retrieve a dataset.

Response Headers:
 
DELETE /api/v1/datasets/(uuid: dataset_id)

Delete a dataset.

PUT /api/v1/datasets/(uuid: dataset_id)

Update dataset details.

If one of the fields is not specified, it will not be updated.

Example request:

{
    "name": "Not Mood",
    "description": "Dataset for mood misclassification.",
    "public": true
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Optional. Name of the dataset.
  • description (string) – Optional. Description of the dataset.
  • public (boolean) – Optional. true to make dataset public, false to make it private.
Response Headers:
 

Rate limiting

The AcousticBrainz API is rate limited via the use of rate limiting headers that are sent as part of the HTTP response headers. Each call will include the following headers:

  • X-RateLimit-Limit: Number of requests allowed in given time window
  • X-RateLimit-Remaining: Number of requests remaining in current time window
  • X-RateLimit-Reset-In: Number of seconds when current time window expires (recommended: this header is resilient against clients with incorrect clocks)
  • X-RateLimit-Reset: UNIX epoch number of seconds (without timezone) when current time window expires [1]

We typically set the limit to 10 queries every 10 seconds per IP address, but these values may change. Make sure you check the response headers if you want to know the specific values.

Rate limiting is automatic and the client must use these headers to determine the rate to make API calls. If the client exceeds the number of requests allowed, the server will respond with error code 429: Too Many Requests. Requests that provide the Authorization header with a valid user token may receive higher rate limits than those without valid user tokens.

[1]Provided for compatibility with other APIs, but we still recommend using X-RateLimit-Reset-In wherever possible

Constants

Constants that are relevant to using the API:

webserver.views.api.v1.core.MAX_ITEMS_PER_BULK_REQUEST = 25

The maximum number of items that you can pass as a recording_ids parameter to bulk lookup endpoints