Welcome to Soundcharts API, the all-in-one source for real-time data on millions of music entities, designed to help you build your distribution dashboard, mobile application, or reporting tool.

Our API is:

• fully REST compliant, serving JSON encoded responses
• blazing fast, the average response time is 200ms (please note that Sandbox can be a little slower making OPTIONS request because of CORS)
• completely unified, making integration easier and faster
• easily testable directly in the documentation

Authentication

Soundcharts API needs special headers to authenticate requests.

x-app-id is used to retrieve your customer rights.
x-api-key is used to authenticate your API user.

Sandbox & production environment

The sandbox environment is free & open to everyone.

The endpoint is located at https://customer.api.soundcharts.com or accessible in the examples here.

You can use the following credentials:

• App ID: soundcharts
• Api key: soundcharts

The production environment is reserved for our registered customers.

The endpoint is also located at https://customer.api.soundcharts.com. Contact us to get your production credentials!

Rate limits & quotas

The response contains an x-quota-remaining header with the number of remaining requests.

We do not set hard rate limits to let you get the data you need as fast as possible. However, we recommend not to exceed a maximum of 10k calls/minute.

All our API plans are subject to monthly quotas.

Once your quota is consumed, new requests will fail with the 429 error code and an explicit error message.

Error management

Soundcharts API follows HTTP specifications regarding error handling, each method describes the available response code it returns

The response always contains an errors array at the root level that can provide more detailed error messages :

{
    "errors": [
      {
        "key": "string",
        "code": 0,
        "message": "string"
      }
    ]
  }

Entities, collections & paginated results

Single object response have the following form:

{
  "type": "string"
  "object": {

  }
}

Collections responses contains an items array and a page object to help you navigate through paged results:

{
  "items": [
  ],
  "page": {
    "offset": 0,
    "total": 100,
    "next": null,
    "previous": null,
    "limit": 100
  },
}

When requesting a collection related to a specific entity (ie getting charts position for a song) a related object containing the basic entity information is present in the response:

{
  "related": {
  }
}

Python SDK

We provide an official Python SDK that includes built-in request handling and error management. To install it, simply run:

 pip install soundcharts

You can find the SDK's GitHub repository here: soundcharts/python-sdk