ListenBrainz API

The ListenBrainz server supports the following end-points for submitting and fetching listens. All endpoints have this root URL:

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

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!

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_id)/listens

Get listens for user user_id. 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 greter than (but not including) this value will be returned.
  • limit – 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:
 

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:

webserver.views.api.MAX_LISTEN_SIZE = 10240

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

webserver.views.api.MAX_ITEMS_PER_GET = 100

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

webserver.views.api.DEFAULT_ITEMS_PER_GET = 25

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

webserver.views.api.MAX_TAGS_PER_LISTEN = 50

The maximum number of tags per listen.

webserver.views.api.MAX_TAG_SIZE = 64

The maximum length of a tag