Report a catalogue stream

post

https://api.7digital.com/1.2/catalogue/log

Report a track that has been streamed to a user who was listening in a radio style playback.

It is recommended to log streams in near real time, or the same day in batch. Before logging actual user data, your Client Success manager will support you through Compliance Testing to ensure logging accuracy and usage of the appropriate endpoint.

OAuth User token

Example request

POST https://api.7digital.com/1.2/catalogue/log?country=EE&userId=141732543&oauth_consumer_key=YOUR_KEY_HERE&...

Multiple plays can be batched by user into a single POST to this endpoint, and the body can be sent in either JSON or XML formats. Streams that are requested as part of pre-fetching functionality, but never played on the device, should still be logged with a zero second play time.

{
  "playLogItem": [
    {
      "endReason": "naturalEnd",
      "userId": "141732543",
      "userAgent": "Device",
      "totalTimePlayed": "12",
      "dateTimePlayed": "2016-12-19T11:39:28.8981203Z",
      "formatId": "33",
      "releaseId": "64705",
      "trackId": "673059"
    }
  ]
}

Example Response

{
    "status": "ok",
    "version": "1.2",
    "playLogs": {
        "count": 1
    }
}

Specific Error Codes

1002 - DateTimePlayed is not within the two month window. Streams must be logged with a date less than 61 days in the past, and cannot be logged before they have happened (ie. DateTimePlayed in the future).

Query Params

userId

string

required

The unique identifier of the user that played that track. For information on creating users click here.

country

string

required

The 2 letter ISO country code, as with our other endpoints. Should be the country where the user originated the stream from (e.g. set to US if the stream was played by a US user). Please note it can only be placed as a query string parameter, not in the POST body, or authorisation headers if those are used.

Form Data

userId

string

required

The unique identifier of the user that played that track. For information on creating users click here.

trackId

int32

required

The MassiveMusic ID of the track that was streamed.

releaseId

int32

required

The MassiveMusic ID of the release that was streamed.

formatId

int32

required

The MassiveMusic ID of the format streamed.

dateTimePlayed

string

required

The date and time when the track was played. Should be in the ISO 8601 format.

totalTimePlayed

int32

required

The total time the track was streamed in seconds.

endReason

string

required

The reason the track play was stopped. This is one of three values "naturalEnd", "userSkipped" or "other." "naturalEnd" would be used to indicate when a track has finished playing in its entirety. "userSkipped" would be used to indicate that a user has chosen to skip the currently playing track. "other" is used when the reason the track has been stopped doesn't fit into the previous catagories, for example when a user changes radio station.

userAgent

string

required

Details of the device model and application version used to play the track. Values over 256 characters will be truncated.