AcousticBrainz Server Documentation

Contents:

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}},
 "mbid_mapping": {"MBID1": "mbid1"}
}

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 returned in a normalised form (all lower-case, separated in groups of 8-4-4-4-12 characters), even if the provided recording MBIDs are not given in this form. In the case that a requested MBID is not given in this normalised form, the value mbid_mapping in the response will be a dictionary mapping user-provided MBIDs to this form.

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_classes – Optional. 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}},
 "mbid_mapping": {"MBID1": "mbid1"}
}

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 returned in a normalised form, even if the provided recording MBIDs are not given in this form. In the case that a requested MBID is not given in this normalised form, the value mbid_mapping in the response will be a dictionary that maps user-provided MBIDs to this form.

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.

If you only need a specific feature and don’t want to download the whole low-level document, you can request specific features using the features parameter. The shape of the returned document will be the same as a full low-level document, and will contain only the specified features as well as the metadata.audio_properties and metadata.version objects.

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.

  • features –

    Optional. A list of features to be returned for each mbid.

    Takes the form feature1;feature2.

    You can specify the following features in a request: LOWLEVEL_INDIVIDUAL_FEATURES.
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_mapping": {"MBID1": "mbid1"}
}

MBID keys are always returned in a normalised form (all lower-case, separated in groups of 8-4-4-4-12 characters), even if the provided recording MBIDs are not given in this form. In the case that a requested MBID is not given in this normalised form, the value mbid_mapping in the response will be a dictionary mapping user-provided MBIDs to this form.

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:
 
  • n – Optional. Integer specifying an offset for a document.
  • map_classes – Optional. If set to ‘true’, map class names to human-readable values

TODO: provide a link to what these mappings are

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:
 
  • n – Optional. 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

webserver.views.api.v1.core.LOWLEVEL_INDIVIDUAL_FEATURES = ['lowlevel.average_loudness', 'lowlevel.dynamic_complexity', 'metadata.audio_properties.replay_gain', 'metadata.tags', 'rhythm.beats_count', 'rhythm.beats_loudness.mean', 'rhythm.bpm', 'rhythm.bpm_histogram_first_peak_bpm.mean', 'rhythm.bpm_histogram_second_peak_bpm.mean', 'rhythm.danceability', 'rhythm.onset_rate', 'tonal.chords_key', 'tonal.chords_scale', 'tonal.key_key', 'tonal.key_scale', 'tonal.tuning_equal_tempered_deviation', 'tonal.tuning_frequency']

Features that can be selected individually from the bulk low-level endpoint

Deployment Practices

We run two instances of AcousticBrainz on the same data.

The beta instance is used to test new features and bugfixes on the actual dataset before being officially deployed into production.

We follow the general MetaBrainz guidelines to deploy, test and release code into beta and production.

Indices and tables