StationSearchRequest

Body for POST /station, which finds a station and creates a play from it in one call.

The example below is the common fallback chain: replay one specific station from 42 seconds in, and if that station has nothing left to play, start any pop radio station instead.

q object[]required

The ordered list of searches to try. An empty array is legal and means "give me the first playable station", which is the simplest way to start music without knowing the customer's station layout.

Array [

typestring

The kind of station to look for: radio, first_play, or replay.

Possible values: [radio, first_play, replay]

filter object

Criteria narrowing which stations this query may match. A station matches when every property of the filter matches it, and an empty object matches every station.

A property is either a field or one of the two combinators.

Fields

A field names a station property. Only name and uuid address the station itself. Every other name is matched against the station's options, so {"genre": "pop"} tests options.genre. Which option names exist depends on how your catalog is tagged. Match one specific station on uuid, which is stable; name is display text and may be edited.

A field's value is one of:

• An exact value. Strings, numbers and booleans compare exactly. Where the option holds an array, the value matches if the array contains it, so {"genre": "rock"} matches a station whose options.genre is ["rock", "pop"].
• A wildcard string, with * at the start, at the end, or at both ends: "Workout*", "*Radio", "*Cycling*". A * anywhere else in the string is matched literally, and there is no way to escape one.
• An operator object holding exactly one of {"$in": [...]}, {"$nin": [...]}, {"$ne": value} or {"$exists": true|false}. $exists: false matches both a missing option and one set to null.

Combinators

$and takes an array of filters, all of which must match. $or takes an array of filters, at least one of which must match. Both nest to any depth.

Either may sit alongside fields, and alongside each other, in the same object. Every property of an object is combined with AND, so

{ "$or": [ { "genre": "pop" }, { "genre": "rock" } ],
  "class": "cycling" }

requires the class and one of the two genres.

{"$or": []} matches no station. {"$and": []} matches every station.

Outside the grammar

Nothing else is supported: no other operators, no dotted paths into nested options, no array as a field value, and no second operator inside one operator object. filter is not validated, so none of these is reported as an error. They match no station, and the search falls through to the next entry in q.

property name*any

Criteria narrowing which stations this query may match. A station matches when every property of the filter matches it, and an empty object matches every station.

A property is either a field or one of the two combinators.

Fields

A field names a station property. Only name and uuid address the station itself. Every other name is matched against the station's options, so {"genre": "pop"} tests options.genre. Which option names exist depends on how your catalog is tagged. Match one specific station on uuid, which is stable; name is display text and may be edited.

A field's value is one of:

• An exact value. Strings, numbers and booleans compare exactly. Where the option holds an array, the value matches if the array contains it, so {"genre": "rock"} matches a station whose options.genre is ["rock", "pop"].
• A wildcard string, with * at the start, at the end, or at both ends: "Workout*", "*Radio", "*Cycling*". A * anywhere else in the string is matched literally, and there is no way to escape one.
• An operator object holding exactly one of {"$in": [...]}, {"$nin": [...]}, {"$ne": value} or {"$exists": true|false}. $exists: false matches both a missing option and one set to null.

Combinators

$and takes an array of filters, all of which must match. $or takes an array of filters, at least one of which must match. Both nest to any depth.

Either may sit alongside fields, and alongside each other, in the same object. Every property of an object is combined with AND, so

{ "$or": [ { "genre": "pop" }, { "genre": "rock" } ],
  "class": "cycling" }

requires the class and one of the two genres.

{"$or": []} matches no station. {"$and": []} matches every station.

Outside the grammar

Nothing else is supported: no other operators, no dotted paths into nested options, no array as a field value, and no second operator inside one operator object. filter is not validated, so none of these is reported as an error. They match no station, and the search falls through to the next entry in q.

Example: {"genre":"pop"}

atnumber

Start offset in seconds for the resulting play. Must be a non-negative number; anything else returns invalidParameter (code 15).

Possible values: >= 0

]

client_idstring

The client the resulting play belongs to. Required, but may instead arrive as a cid cookie or a client_id query parameter — see Identifying a client. Values longer than 23 characters are silently truncated.

Possible values: <= 23 characters

formatsstring

Comma-separated list of acceptable codecs, in preference order, e.g. aac,mp3. Valid codecs are mp3 and aac.

max_bitrateinteger

Upper bound on the delivered bitrate, in kbps.

StationSearchRequest

{
  "client_id": "FgT1_Yzvr_e05ANk2uCYdZi",
  "q": [
    {
      "type": "replay",
      "filter": {
        "uuid": "Qm4x_Lp82_c19BXk7uDReWq"
      },
      "at": 42
    },
    {
      "type": "radio",
      "filter": {
        "genre": "pop"
      }
    }
  ],
  "formats": "aac,mp3",
  "max_bitrate": 128
}