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:
 
Status Codes:
Response Headers:
 
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:
 
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
}
Parameters:
  • user_name – the MusicBrainz ID of the user whose data is needed
Status Codes:
  • 200 OK – Yay, you have data!
Response Headers:
 
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:
 
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