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:
 

Similarity

GET /api/v1/similarity/(metric)/between/

Get the distance measure for similarity between two MBIDs. The distance measure will correspond to the index of the specified metric.

The metrics available are shown here BASE_METRIC_NAMES.

Example response:

{"metric": [<distance_vector>]}

NOTE If an (MBID, offset) combination specified does not exist, or is not present in the index, an empty dictionary will be returned.

Query Parameters:
 
  • recording_ids –

    Required. A list of the two recordings for which similarity should be found between.

    Takes the form mbid[:offset]:mbid[:offset]. Offsets are optional, and should be integers >= 0
Response Headers:
 
GET /api/v1/similarity/(metric)/

Get the most similar submissions to multiple (MBID, offset) combinations.

Example response:

{"mbid1": {"offset1": [(most_similar_mbid, offset),
                        ...,
                    (least_similar_mbid, offset)],
          "offset2": [(most_similar_mbid, offset),
                        ...,
                    (least_similar_mbid, offset)]
         },
 ...,

 "mbidN": {"offset1": [(most_similar_mbid, offset),
                        ...,
                       (least_similar_mbid, offset)]
          }
}

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.

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
  • n_neighbours – Optional. The number of similar recordings that should be returned for each item in recording_ids (1-1000). Default is 200 recordings.
  • metric – Required. String specifying the metric name to be used when finding the most similar recordings. The metrics available are shown here BASE_METRIC_NAMES.
  • threshold – Optional. Only return items whose distance from the query recording is less than this (0-1). This may result in the number of returned items being less than n_neighbours if it is set.
  • remove_dups – Optional. If samescore, remove duplicate submissions that have the same score. If all, remove all duplicate MBIDs even if they have different scores, returning only the submission with the lowest score. This may result in the number of returned items being less than n_neighbours if it is set.
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_changes_rate', 'tonal.chords_key', 'tonal.chords_scale', 'tonal.key_key', 'tonal.key_scale', 'tonal.key_strength', 'tonal.tuning_equal_tempered_deviation', 'tonal.tuning_frequency']

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

similarity.metrics.BASE_METRIC_NAMES = ['mfccs', 'mfccsw', 'gfccs', 'gfccsw', 'key', 'bpm', 'onsetrate', 'moods', 'instruments', 'dortmund', 'rosamerica', 'tzanetakis']

Available similarity metrics