Zum Inhalt springen
ARD Eventhub
Esc
↑↓navigate↵open⌘Jpreview

Distribute a now-playing track

POST/events/de.ard.eventhub.v1.radio.track.playing
Authorization
AuthorizationBearer token (JWT) · headerrequired
Request body
requiredapplication/json
New event to be distributed to subscribers. The Eventhub format validation expects only a subset of these variables as minimum set. All other fields are technically optional, but **highly encouraged** to be included, so a best-possible metadata exchange is possible. The subset is defined in the list of required fields of Schemas `eventV1PostBody`, resulting in this body: ```json { "type": "music", "start": "2020-01-19T06:00:00+01:00", "title": "Song name", "services": [ { ... } ], "playlistItemId": "swr3-5678" } ``` Required fields not specified in the Schema, will cause your request to fail. The `id` is inserted by Eventhub as string-formatted number, but might be a true string in the future, do not expect this string to remain numbers only!
eventstring
If set, it needs to match the URL event parameter
Allowed:de.ard.eventhub.v1.radio.track.playingde.ard.eventhub.v1.radio.track.next
typestringrequired
The type of the element that triggered this event. See additional file in docs for details.
Allowed:audiocommercialjinglelivemusicnewstrafficweather
startstringrequired
ISO8601 compliant timestamp
lengthnumberrequired
Estimated length of the element in seconds. Must be set to a positive number (not 0 or null). The end of the current element is defined by the start of the next element.
titlestringrequired
Representative title for external use
artiststring | null
Pre-formatted artist information
contributorscontributor[] | null
Full details about involved artists if available
Show properties
Array of contributor
contributor
servicesservices[]required
The playing stations unique Service-IDs. Do not include the Service-Type suffix.
Show properties
Array of services
services
referencesreference[] | null
related external entities
Show properties
Array of reference
reference
playlistItemIdstringrequired
Unique identifier (within a publisher) to connect next and playing items if needed
hfdbIdsstring[] | null
Can reference all available tracks in ARD HFDB instances. Should ideally at least include the common ZSK instance.
externalIdstring | null
Can reference the original ID in the publisher's system
isrcstring | null
Appropriate ISRC code if track is a music element
upcstring | null
Corresponding reference to an album where such ISRC was published
mpnstring | null
If available the reference to the original delivery from MPN
mediamediaItem[] | null
Can contain an array of media files like cover, artist, etc.
Show properties
Array of mediaItem
mediaItem
pluginseventPlugin[] | null
Highly optional field for future third-party metadata distribution or other connected services
Show properties
Array of eventPlugin
eventPlugin
idstring
ID gets inserted by Eventhub as string-formatted number, but might be a true string in the future, do not expect this string to remain numbers only!
Responses
201 Event created *Note:* The first request of an event for an externalId that is not registered yet, will return the status `failed: 1`. This indicates that a new topic for the externalId has been created, and the request needs to be repeated: ```json "statuses": { "published": 0, "blocked": 0, "failed": 1 } ``` If the request returns the status `blocked: 1`, it indicates that you are not allowed to publish events under the given publisherId.
statusesobjectrequired
Show properties
publishedintegerrequired
min -9007199254740991 · max 9007199254740991
blockedintegerrequired
min -9007199254740991 · max 9007199254740991
failedintegerrequired
min -9007199254740991 · max 9007199254740991
eventeventV1PostBodyrequired
Show properties
eventV1PostBody
tracestring | nullrequireddeprecated
Always null. Deprecated; may be removed in a future release.
400Bad Request (invalid input)
messagestringrequired
errorsopenApiErrorItem[]required
min items 1
Show properties
Array of openApiErrorItem
openApiErrorItem
tracestring | nullrequireddeprecated
Always null. Deprecated; may be removed in a future release.
401Missing authentication
messagestringrequired
errorsopenApiErrorItem[]required
min items 1
Show properties
Array of openApiErrorItem
openApiErrorItem
tracestring | nullrequireddeprecated
Always null. Deprecated; may be removed in a future release.
403Invalid authorization
messagestringrequired
errorsopenApiErrorItem[]required
min items 1
Show properties
Array of openApiErrorItem
openApiErrorItem
tracestring | nullrequireddeprecated
Always null. Deprecated; may be removed in a future release.
413Payload Too Large (JSON body exceeds 400kb limit)
messagestringrequired
errorsopenApiErrorItem[]required
Show properties
Array of openApiErrorItem
openApiErrorItem
tracestring | nullrequireddeprecated
Always null. Deprecated; may be removed in a future release.
500Internal server error
messagestringrequired
tracestring | nullrequireddeprecated
Always null. Deprecated; may be removed in a future release.
Request
curl -X POST "/events/de.ard.eventhub.v1.radio.track.playing" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "de.ard.eventhub.v1.radio.track.playing",
  "type": "music",
  "start": "2020-01-19T06:00:00+01:00",
  "length": 240,
  "title": "Song name",
  "artist": "Sam Feldt feat. Someone Else",
  "contributors": [
    null
  ],
  "services": [
    null
  ],
  "references": [
    null
  ],
  "playlistItemId": "swr3-5678",
  "hfdbIds": [
    "swrhfdb1.KONF.12345",
    "zskhfdb1.KONF.12345"
  ],
  "externalId": "M012345.001",
  "isrc": "DE012345678",
  "upc": "string",
  "mpn": "string",
  "media": [
    null
  ],
  "plugins": [
    null
  ],
  "id": "1234567890"
}'
Response
{
  "statuses": {
    "published": 1,
    "blocked": 0,
    "failed": 0
  },
  "event": null,
  "trace": null
}