Skip to main content

Station discovery

Three routes find you a station, and they suit different apps. This page assumes you have a session and a CLIENT_ID; see Session.

Every command below was run against https://feed.fm/api/v3 with the demo/demo test credentials and shows what actually came back.

The three routes​

  • The stations list in the POST /session response. A client can reserve a play from any station in this list with no further lookup. This is the fastest path to audio.

  • POST /station searches for a station and creates a play from it in one call, for an app that knows what it wants by name or by filter. An empty query, q: [], means "give me the first playable station":

    curl -sS -u demo:demo -X POST https://feed.fm/api/v3/station \
      -H 'Content-Type: application/json' \
      -d "{\"client_id\":\"$CLIENT_ID\",\"q\":[]}"

    A named search filters on the station's name or uuid:

    curl -sS -u demo:demo -X POST https://feed.fm/api/v3/station \
      -H 'Content-Type: application/json' \
      -d "{\"client_id\":\"$CLIENT_ID\",\"q\":[{\"filter\":{\"name\":\"Station Two\"}}]}"
    {
      "success": true,
      "play": {
        "id": "200950351407565",
        "station": { "id": "199835930", "name": "Station Two", "uuid": "94102d35-60d5-4494-bc0a-5288cdb29319" }
      }
    }

    That response already contains your play. Skip the POST /play step in Station playback and go straight to start using this play.id.

  • GET /station lists and pages every station available to the app, for an app building a browsable menu:

    curl -sS -u demo:demo "https://feed.fm/api/v3/station?client_id=$CLIENT_ID"

Carrying a station forward​

The examples in Station playback pull from a station by id. Export one from whichever route you used:

export STATION_ID="199835928"

STATION_ID stays the same for as long as you keep playing that station.

Persist uuid, never id​

A station's numeric id is a specific version of that station, and changes to that station are published under a new station id; the uuid is the only value that survives a republish. If you saved a uuid and later need to reserve a play from that station, resolve it with a POST /station search filtered on uuid, as shown above, rather than reusing an old id.

Use caution if keying off name since it is display text and can be edited.

The session list is a subset​

Two details about that subset relationship are easy to miss:

  • The session's stations list is a subset of the app's (and placement's) stations, not the whole catalog. An app that builds its menu from the session response and stops there will quietly show fewer stations than the app actually offers, and nothing in the response says so. GET /station returns the full list. (The demo credentials used on this page happen to return the same two stations from both calls, so you will not see the difference reproduced here. On a real app with a larger catalog, the two lists differ.)
  • Search is not limited to that subset. POST /station searches every station available to the app, including ones the session response never mentioned. A client does not have to list stations before it can search for one by name or uuid.