ListenBrainz API¶

The ListenBrainz server supports the following end-points for submitting and fetching listens. All endpoints have this root URL for our current production site [1].

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

Note: All ListenBrainz services are only available on HTTPS!

[1]	The beta endpoints (i.e. `beta.listenbrainz.org`) were deprecated in Fall 2017. If you were using this endpoint, please use the current, production endpoints instead.

Reference¶

API Calls¶

POST /1/submit-listens¶

Submit listens to the server. A user token (found on https://listenbrainz.org/profile/ ) 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:
	Authorization – Token <user token>
Status Codes:	200 OK – listen(s) accepted. 400 Bad Request – invalid JSON sent, see error message for details. 401 Unauthorized – invalid authorization. See error message for details.
Response Headers:
	Content-Type – application/json

GET /1/validate-token¶

Check whether a User Token is a valid entry in the database.

In order to query this endpoint, send a GET request with the token to check as the token argument (example: /validate-token?token=token-to-check)

A JSON response will be returned, with one of two codes.

Status Codes:	200 OK – The user token is valid/invalid. 400 Bad Request – No token was sent to the endpoint.

GET /1/users/(user_list)/recent-listens¶

Fetch the most recent listens for a comma separated list of users. Take care to properly HTTP escape user names that contain commas!

Response Headers:
Status Codes:	200 OK – Fetched listens successfully. 400 Bad Request – Your user list was incomplete or otherwise invalid.
	Content-Type – application/json

GET /1/user/(user_name)/playing-now¶

Get the listen being played right now for user user_name.

This endpoint returns a JSON document with a single listen in the same format as the /user/<user_name>/listens endpoint, with one key difference, there will only be one listen returned at maximum and the listen will not contain a listened_at element.

The format for the JSON returned is defined in our JSON Documentation.

Response Headers:
Status Codes:	200 OK – Yay, you have data!
	Content-Type – application/json

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.

Response Headers:
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!
	Content-Type – application/json

GET /1/latest-import¶

Get the timestamp of the newest listen submitted by a user 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
}

Response Headers:
Parameters:	user_name – the MusicBrainz ID of the user whose data is needed
Status Codes:	200 OK – Yay, you have data!
	Content-Type – application/json

POST /1/latest-import¶

Update the timestamp of the newest listen submitted by a user in an import to ListenBrainz.

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/profile/.

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

{
  'ts': 0
}

Request Headers:
	Authorization – Token <user token>
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.

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: 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 [2]

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.

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

Timestamps¶

All timestamps used in ListenBrainz 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