StationSearchSuccess

The successful POST /station body: the station that was found, already embedded in the play it produced, plus the placement that station belongs to.

successbooleanrequired

Always true on this payload.

Example: true

play object

A play as returned by POST /station. Identical to Play except that station is always present and is always the complete Station object rather than the minimal one.

This play should be considered invalid if a start call is made against another play before starting playback of this song.

idstringrequired

The play id. Numeric, but always serialized as a string. Every subsequent call about this play (start, elapse, complete, skip, invalidate, like, dislike, unlike) is addressed by this id.

Example: 1122334455

audio_file objectrequired

A single playable, transcoded audio file plus its music metadata. Several properties are emitted only when they apply, so their absence is meaningful — see the individual descriptions.

idstringrequired

The Feed.fm audio file id. Numeric, but always serialized as a string.

Example: 9876543

duration_in_secondsintegerrequired

Playback length of the file, in whole seconds.

Example: 213

codecstringrequired

The codec of the delivered file, e.g. mp3 or aac. Selected from the formats the caller asked for.

Example: mp3

urluri

The URL to stream or download. This may be a CloudFront-signed URL that expires roughly 20 minutes after it was issued, so it should be used promptly and never cached long-term. Absent when the play was created without a resolvable URL. If this URL is unplayable because it has expired (it has an Expires query parameter that is a unix epoch timestamp, and it is in the past), then a new POST /play request should be made to generate a new, valid, URL rather than a call to POST /play/{play_id}/invalidate.

Signed URLs include app_id (the authenticated application's ID), client_id (the resolved client's UUID), and, when available, audio_file_id and play_id in the query string. These IDs are covered by the CloudFront signature. Use the complete URL as returned: changing any ID invalidates the URL. These URLs are not bound to an IP address; their 20-minute expiry still applies.

bitrateinteger

Delivered bitrate in kbps. Emitted only when the underlying play has a known bitrate.

Example: 128

track objectrequired

The individual song an audio file renders.

idstringrequired

The Feed.fm track id. Numeric, but always serialized as a string.

Example: 1234567

titlestringrequired

The song title.

Example: Real Live Flesh

release objectrequired

The album the track was released on. Named release throughout the API; there is no album key.

idstringrequired

The Feed.fm release id. Numeric, but always serialized as a string.

Example: 89012

titlestringrequired

The album title.

Example: Kissing The Beehive

artist objectrequired

The performing artist for a track.

idstringrequired

The Feed.fm artist id. Numeric, but always serialized as a string.

Example: 345

namestringrequired

The artist name.

Example: Kissing The Beehive

extra objectrequired

Free-form per-file metadata stored alongside the audio file and passed through verbatim. The keys vary by catalog and by client; treat any key not documented here as optional and unstable. Commonly seen keys include trim_start and trim_end.

property name*any

Free-form per-file metadata stored alongside the audio file and passed through verbatim. The keys vary by catalog and by client; treat any key not documented here as optional and unstable. Commonly seen keys include trim_start and trim_end.

likedboolean

Present and true when this client has liked the track. The key is omitted entirely when the track is not liked — it is never sent as false, so callers must test for presence rather than for value.

Possible values: [true]

can_seekboolean

Present and true when the licensing for this play permits seeking within the file. Omitted entirely otherwise; never sent as false.

Possible values: [true]

can_cacheboolean

Present and true when the file may be cached locally for offline playback. Omitted entirely otherwise; never sent as false.

Possible values: [true]

previewboolean

Present and true when this play is a preview rather than a reportable play. Omitted entirely otherwise; never sent as false.

Possible values: [true]

replaygain_track_gainnumber

ReplayGain track adjustment in dB, to be applied by the player for consistent loudness. Emitted only when a non-zero value is known.

Example: -6.5

start_atnumber

Offset in seconds the player should start at, rather than the beginning of the file. Emitted only when non-zero.

Example: 30

station objectrequired

A full station. The optional properties are each emitted only under the conditions described below, so their absence carries meaning.

idstringrequired

The station id. Numeric, but always serialized as a string. This value changes with the 'placement id', and so should not be persisted - use the uuid property instead.

Example: 727

namestringrequired

The station's display name.

Example: Pop Rock

on_demandintegerrequired

Whether the station is an on-demand station: 1 for yes, 0 for no.

Possible values: [0, 1]

pre_gainnumbernullablerequired

Station-level gain adjustment in dB, to be applied before playback. null when the station has no adjustment configured.

options objectrequired

Free-form, customer-configured options attached to a station. Contents vary per customer; unknown keys should be passed through rather than rejected.

crossfade_secondsnumber

Crossfade duration for the station, in seconds.

property name*any

Free-form, customer-configured options attached to a station. Contents vary per customer; unknown keys should be passed through rather than rejected.

uuidstringrequired

The station's stable external identifier. Unlike id, it does not change over time.

Example: FgT1_Yzvr_e05ANk2uCYdZi

crossfade_secondsnumbernullablerequired

The station's own crossfade duration in seconds. null when unset. This may differ from the customer-configured options.crossfade_seconds; the two can disagree.

single_playbooleanrequired

true when the station is a single-play station — one track, not a continuous stream.

last_updateddate-timerequired

When the station's contents last changed. Clients use this to decide whether a cached offline copy is stale.

last_play_startdate-time

When this client last started a play on this station. Emitted only when such a play exists, so it is absent for new clients and for stations the client has never played.

expire_datedate-time

When a downloaded offline copy of this station should be considered expired — three weeks from the moment of the response. Emitted only for entries in offline_stations on the session response; it never appears on streaming stations, nor on the station-list routes even when those are listing offline stations.

country_inclusion_modestring

How the countries list should be read: include means the station is available only in those countries, exclude means it is available everywhere but those.

Example: include

countriesstring[]

Two-letter ISO 3166-1 alpha-2 country codes the country_inclusion_mode applies to. Emitted only when country_inclusion_mode is exactly include or exclude, and never null in that case — when the property is present it always carries the list. Absent for any other mode.

placement objectrequired

A placement — an immutable collection of stations and the playback options that apply across them.

idstringrequired

The placement id. Numeric, but always serialized as a string.

Example: 10955

options objectrequired

Free-form, customer-configured placement options, passed through verbatim. Contents vary per customer.

property name*any

Free-form, customer-configured placement options, passed through verbatim. Contents vary per customer.

StationSearchSuccess

{
  "success": true,
  "play": {
    "id": "1122334455",
    "audio_file": {
      "id": "9876543",
      "duration_in_seconds": 213,
      "codec": "mp3",
      "url": "string",
      "bitrate": 128,
      "track": {
        "id": "1234567",
        "title": "Real Live Flesh"
      },
      "release": {
        "id": "89012",
        "title": "Kissing The Beehive"
      },
      "artist": {
        "id": "345",
        "name": "Kissing The Beehive"
      },
      "extra": {},
      "liked": true,
      "can_seek": true,
      "can_cache": true,
      "preview": true,
      "replaygain_track_gain": -6.5
    },
    "start_at": 30,
    "station": {
      "id": "727",
      "name": "Pop Rock",
      "on_demand": 0,
      "pre_gain": 0,
      "options": {
        "crossfade_seconds": 0
      },
      "uuid": "FgT1_Yzvr_e05ANk2uCYdZi",
      "crossfade_seconds": 0,
      "single_play": true,
      "last_updated": "2024-07-29T15:51:28.071Z",
      "last_play_start": "2024-07-29T15:51:28.071Z",
      "expire_date": "2024-07-29T15:51:28.071Z",
      "country_inclusion_mode": "include",
      "countries": [
        "US"
      ]
    }
  },
  "placement": {
    "id": "10955",
    "options": {}
  }
}