ListenBrainz API for Beta

The ListenBrainz server supports the following end-points for submitting and fetching listens. All endpoints have this root URL for our current “pre-beta” site:

  • Beta API Root URL: https://beta-api.listenbrainz.org
  • Beta Web Root URL: https://beta.listenbrainz.org

Once we go to a full beta, we’re going to move to the production URLs:

  • Production API Root URL: https://api.listenbrainz.org
  • Production Web Root URL: https://listenbrainz.org

The current site at listenbrainz.org will move to alpha.listenbrainz.org once we’re in beta.

NOTE: All of ListenBrainz services are available on HTTPS only!

Reference

API Calls

POST /1/submit-listens

Submit listens to the server. A user token (found on https://listenbrainz.org/user/import ) must be provided in the Authorization header!

Listens should be submitted for tracks when the user has listened to half the track or 4 minutes of the track, whichever is lower. If the user hasn’t listened to 4 minutes or half the track, it doesn’t fully count as a listen and should not be submitted.

For complete details on the format of the JSON to be POSTed to this endpoint, see JSON Documentation.

Request Headers:
 
Status Codes:
Response Headers:
 
GET /1/latest-import

Get and update the timestamp of the newest listen submitted in previous imports to ListenBrainz.

In order to get the timestamp for a user, make a GET request to this endpoint. The data returned will be JSON of the following format:

{

‘musicbrainz_id’: the MusicBrainz ID of the user,

‘latest_import’: the timestamp of the newest listen submitted in previous imports. Defaults to 0

}

Parameters:
  • user_name – the MusicBrainz ID of the user whose data is needed
Status Codes:
  • 200 OK – Yay, you have data!
Response Headers:
 

In order to update the timestamp of a user, you’ll have to provide a user token in the Authorization Header. User tokens can be found on https://listenbrainz.org/user/import .

The JSON that needs to be posted must contain a field named ts in the root with a valid unix timestamp.

Request Headers:
 
Status Codes:
  • 200 OK – latest import timestamp updated
  • 400 Bad Request – invalid JSON sent, see error message for details.
  • 401 Unauthorized – invalid authorization. See error message for details.
POST /1/latest-import

Get and update the timestamp of the newest listen submitted in previous imports to ListenBrainz.

In order to get the timestamp for a user, make a GET request to this endpoint. The data returned will be JSON of the following format:

{

‘musicbrainz_id’: the MusicBrainz ID of the user,

‘latest_import’: the timestamp of the newest listen submitted in previous imports. Defaults to 0

}

Parameters:
  • user_name – the MusicBrainz ID of the user whose data is needed
Status Codes:
  • 200 OK – Yay, you have data!
Response Headers:
 

In order to update the timestamp of a user, you’ll have to provide a user token in the Authorization Header. User tokens can be found on https://listenbrainz.org/user/import .

The JSON that needs to be posted must contain a field named ts in the root with a valid unix timestamp.

Request Headers:
 
Status Codes:
  • 200 OK – latest import timestamp updated
  • 400 Bad Request – invalid JSON sent, see error message for details.
  • 401 Unauthorized – invalid authorization. See error message for details.
GET /1/user/(user_name)/listens

Get listens for user user_name. The format for the JSON returned is defined in our JSON Documentation.

If none of the optional arguments are given, this endpoint will return the DEFAULT_ITEMS_PER_GET most recent listens. The optional max_ts and min_ts UNIX epoch timestamps control at which point in time to start returning listens. You may specify max_ts or min_ts, but not both in one call. Listens are always returned in descending timestamp order.

Parameters:
  • max_ts – If you specify a max_ts timestamp, listens with listened_at less than (but not including) this value will be returned.
  • min_ts – If you specify a min_ts timestamp, listens with listened_at greater than (but not including) this value will be returned.
  • count – Optional, number of listens to return. Default: DEFAULT_ITEMS_PER_GET . Max: MAX_ITEMS_PER_GET
Status Codes:
  • 200 OK – Yay, you have data!
Response Headers:
 

Rate limiting

The ListenBrainz 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: The number of requests allowed in a given time window.
  • X-RateLimit-Remaining: The number of requests remaining in the current time window.
  • X-RateLimit-Reset-In: The number of seconds when the current time window expires. We recommend you use this header, since it is resilient against clients with incorrect clocks.
  • X-RateLimit-Reset: The UNIX epoch number of seconds (without timezone) when the current time window expires. This is provided for compatibility with other APIs, but we recommend using the X-Ratelimit-Reset-In header.

The rate limiting is automatic and the client must use these headers to determine the rate at which calls to the API can be made. 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.

Timestamps

All timestamps used in this project are UNIX epoch timestamps in UTC. When submitting timestamps to us, please ensure that you have no timezone adjustments on your timestamps.

Constants

Constants that are releavant to using the API:

listenbrainz.webserver.views.api_tools.MAX_LISTEN_SIZE = 10240

Maximum overall listen size in bytes, to prevent egregious spamming.

listenbrainz.webserver.views.api_tools.MAX_ITEMS_PER_GET = 100

The maximum number of listens returned in a single GET request.

listenbrainz.webserver.views.api_tools.DEFAULT_ITEMS_PER_GET = 25

The default number of listens returned in a single GET request.

listenbrainz.webserver.views.api_tools.MAX_TAGS_PER_LISTEN = 50

The maximum number of tags per listen.

listenbrainz.webserver.views.api_tools.MAX_TAG_SIZE = 64

The maximum length of a tag