JSON Documentation

Note

Do not submit copyrighted information in these fields!

Submission JSON

To submit a listen via our API (see: ListenBrainz API), POST a JSON document to the submit-listens endpoint. Submit one of three types JSON documents:

  • single: Submit single listen

    • Indicates user just finished listening to track
    • Only a single track may be specified in payload
  • playing_now: Submit playing_now notification

    • Indicates that user just began listening to track
    • payload contains only one track
    • Submitting playing_now documents is optional
    • Timestamp must be omitted from a playing_now submission.
  • import: Submit previously saved listens

    • payload may contain more than one listen, but complete document may not exceed MAX_LISTEN_SIZE bytes in size

The listen_type element defines different types of submissions. The element is placed at the top-most level of the JSON document. The only other required element is the payload element. This provides an array of listens – the payload may be one or mote listens (as designated by listen_type):

{
  "listen_type": "single",
  "payload": [
      --- listen data here ---
  ]
}

A sample listen payload may look like:

{
  "listened_at": 1443521965,
  "track_metadata": {
    "additional_info": {
      "release_mbid": "bf9e91ea-8029-4a04-a26a-224e00a83266",
      "artist_mbids": [
        "db92a151-1ac2-438b-bc43-b82e149ddd50"
      ],
      "recording_mbid": "98255a8c-017a-4bc7-8dd6-1fa36124572b",
      "tags": [ "you", "just", "got", "rick rolled!"]
    },
    "artist_name": "Rick Astley",
    "track_name": "Never Gonna Give You Up",
    "release_name": "Whenever you need somebody"
  }
}

A complete submit listen JSON document may look like:

{
  "listen_type": "single",
  "payload": [
    {
      "listened_at": 1443521965,
      "track_metadata": {
        "additional_info": {
          "release_mbid": "bf9e91ea-8029-4a04-a26a-224e00a83266",
          "artist_mbids": [
            "db92a151-1ac2-438b-bc43-b82e149ddd50"
          ],
          "recording_mbid": "98255a8c-017a-4bc7-8dd6-1fa36124572b",
          "tags": [ "you", "just", "got", "rick rolled!"]
        },
        "artist_name": "Rick Astley",
        "track_name": "Never Gonna Give You Up",
        "release_name": "Whenever you need somebody"
      }
    }
  ]
}

Fetching listen JSON

The JSON documents returned from our API look like the following:

{
  "payload": {
    "count": 25,
    "user_id": "-- the MusicBrainz ID of the user --",
    "listens": [
      "-- listen data here ---"
    ]
  }
}

The number of listens in the document are returned by the top-level count element. The user_id element contains the MusicBrainz ID of the user whose listens are being returned. The other element is the listens element. This is a list which contains the listen JSON elements (described above).

Payload JSON details

A minimal payload must include the listened_at, track_metadata/artist_name and track_metadata/track_name elements:

{
  "listened_at": 1443521965,
  "track_metadata": {
    "artist_name": "Rick Astley",
    "track_name": "Never Gonna Give You Up",
  }
}

artist_name and track_name elements must be simple strings, while the listened_at element must be an integer.

Add additional metadata you may have for a track to the additional_info element. Any additional information allows us to better correlate your listen data to existing MusicBrainz-based data. If you have MusicBrainz IDs availble, submit them!

The following optional elements may also be included in the track_metadata element:

element description
release_name the name of the release this recording was played from.

The following optional elements may also be included in the additional_info element. If you do not have the data for any of the following fields, omit the key entirely:

element description
artist_mbids A list of MusicBrainz Artist IDs, one or more Artist IDs may be included here. If you have a complete MusicBrainz artist credit that contains multiple Artist IDs, include them all in this list.
release_group_mbid A MusicBrainz Release Group ID of the release group this recording was played from.
release_mbid A MusicBrainz Release ID of the release this recording was played from.
recording_mbid A MusicBrainz Recording ID of the recording that was played.
track_mbid A MusicBrainz Track ID associated with the recording that was played.
work_mbids A list of MusicBrainz Work IDs that may be associated with this recording.
tracknumber The tracknumber of the recording. This first recording on a release is tracknumber 1.
isrc The ISRC code associated with the recording.
spotify_id The Spotify track URL associated with this recording. e.g.: http://open.spotify.com/track/1rrgWMXGCGHru5bIRxGFV0
tags A list of user defined tags to be associated with this recording. These tags are similar to last.fm tags. For example, you have apply tags such as punk, see-live, smelly. You may submit up to MAX_TAGS_PER_LISTEN tags and each tag may be up to MAX_TAG_SIZE characters large.

At this point, we are not scrubbing any superflous elements that may be submitted via the additional_info element. We’re open to see how people will make use of these unspecified fields and may decide to formally specify or scrub elements in the future.