StationSearchQuery

One candidate in a POST /station search. The searches are tried in order and the first that yields a playable track wins, which lets a client express a fallback chain such as "replay this track, else start a radio station".

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

StationSearchQuery

{
  "type": "radio",
  "filter": {
    "genre": "pop"
  },
  "at": 0
}