Feed.fm API

Getting started with the Feed.fm API is easy. Our core offering is a simple REST interface over HTTP/HTTPS. We have SDKS to simplify integration in popular environments: iOS/Objective-C, Android/Java, Unity/C#, and Web/Javascript.

Introduction

Overview and Concepts

At the highest level, a feed.fm client pulls music from a placement that has been created and is managed via the feed.fm dashboard.

A placement may hold any number of stations that contain audio file collections. Stations and audio files may be added or removed from a placement at any time.

To pull music from the feed.fm server, a client repeatedly asks the server to create and return a play from one of the stations in a placement. The play returned to the client holds meta-data for a single audio file and a URL that points to audio data.

Once a play has been created, the client may retrieve and start playing the referenced audio file. The client must inform the server when playback initiates and completes, and optionally may inform the server about the progress of playback.

Clients must retrieve and start plays sequentially so that the server knows what is being played and can enforce restrictions on playback order and skip limits when new play requests are sent.

Client Identification

All devices running clients that access the feed.fm service must request and hold onto a persistant client device identifier. The client device identifier is passed to the server with every request to enforce restrictions on playback order and skip limits, and to also to estimate session times.

Authentication

All authenticated requests require the client to hold a set of consumer credentials in the form of a public token and a private key. These can be created and revoked via the feed.fm management interface.

Credentials are sent to the server in requests via an OAuth 1.0a signature for HTTP, or via a basic access authentication 'Authorization' header for HTTPS. Further details are in the REST documentation.

iOS SDK

iOS SDK on GitHub

An Objective-C client library that wraps the REST API is available at:

https://github.com/fuzz-radio/iOS-SDK

The repository contains usage instructions and a sample application.

Unity SDK

Unity SDK on GitHub

A C# library that uses the REST API is available here:

https://github.com/fuzz-radio/Unity-Native-SDK

Instructions, along with an installable unity package are available here.

Javascript SDK

Javascript SDK on GitHub

A Javascript client library that wraps the REST API is available at:

https://github.com/fuzz-radio/Javascript-SDK

The repository contains usage instructions and a sample application.

Android SDK

Android SDK on GitHub

An Android client library that wraps the REST API is available at:

https://github.com/fuzz-radio/Android-SDK

The repository contains usage instructions and a sample application. Additionally, this SDK contains a fully-built UI that can be pasted right into your application.

REST API

Response format

Responses to all resource calls are represented as JSON objects. Minimally, every response indicates wether the call was successful or not and, if not, includes a unique error code and descriptive message if the call wasn't successful.

A successful request always minimally returns:

{
  "success" : true
}
        
A failed request always minimally returns an error object to describe what went wrong, which contains a feed-specific error code, a human readable description of the error, and the HTTP status code associated with the error (see 'Error codes' below for why the HTTP status code is included).
{
  "success" : false,
  "error" : {
    "code" : 123,
    "message" : "human readable error for code 123",
    "status": 200
  }
}
        

Error codes

Listed below are general error codes that could be returned from any resource call.

Note that the response message returned from the server will often have more detailed information about why a particular error occurred. For instance, error 17 (missing object) should describe which object is missing in the message response.

For clients that are unable to access response bodies for non-200 status HTTP responses, all endpoints accept a 'force200=1' parameter, which causes the server to always respond with HTTP 200 status.

Error Code HTTP Status Code Description
5 401 Invalid credentials. Credentials are missing or invalid.
6 401 Forbidden. Access forbidden to the requested resource.
15 400 Invalid parameter value. See error message for details.
16 400 Missing required parameter. See error message for details.
17 404 No such object. The requested resource couldn't be found.
18 500 Unhandled internal error.

Each resource may have additional error codes, specific to the resource. These are listed in the documentation for each resource.

Authentication

Certain requests require authentication, and there are two options: HTTPS+Basic Auth and Oauth.

HTTPS + Basic Auth

For this method, clients merely use the 'Basic' HTTP authentication scheme (RFC 2617) over an HTTPS connection.

The 'Basic' scheme requires a simple 'Authorization' header to be passed with the request, along with base-64 encoded credentials:

          Authorization: Basic Yjg4MTU1MGU5MmUwOWIwMzQyN2Q0MTEzMzMzOWNhNjVhNWMzM2EwMDphNzVlNjMzMzFkOGZlMzhhN2I0YWYxNzJlMGY5NGJiY2QwNzkxYmU4 
        

The encoded portion of the header above is constructed by concatenating:

          token ":" secret
        

(where 'token' and 'secret' are provided via the developer interface) and base-64 encoding the string. The example above was constructed with a 'token' value of 'b881550e92e09b03427d41133339ca65a5c33a00' and a 'secret' value of 'a75e63331d8fe38a7b4af172e0f94bbcd0791be8'.

OAuth

Clients may also use a two legged, HMAC-SHA256 version of OAuth Core 1.0 (RFC 5849) without access tokens, leaning on the interpretation described in Eran Hammer's OAuth Guide.

Further documentation of this will be forthcoming - in the meantime we suggest you use the simpler HTTPS + Auth method.

GET oauth/time

Description

Retrieves the current time on the server, for use with synchronizing the client clock with the server for OAuth signatures.

This method doest not require any authentication and should always successfully return a value.

URL http://feed.fm/api/v2/oauth/time
Parameters

None

Error Codes

Only the generic error codes

Response

A Unix timestamp, equal to the number of seconds since Jan 1, 1970 UTC.

Sample Response

{
  "success" : true,
  "time" : 1359958971
}
                

POST access_token

Description

Creates a time-limited set of credentials for accessing the API.

This endpoint may be used to create a token/secret pair that can be used by API clients rather than the primary 'consumer' token/secret provided via the Feed.fm web interface. The credentials created via this interface will only be good for a limited period of time and can be programmatically revoked to prevent unwanted parties using them indefinitely.

The intended scenario for this is for web clients. When a request is made for page X, the server first submits a 'POST /access_token' to feed.fm and retrieves a token/secret pair. That token secret pair is placed in page X where the javascript can use it just as if it were the primary 'consumer' token/secret. The benefit to this is that the web site visitor never has access to the primary secret and the web server can revoke these temporary credentials when the user logs out or set a limit on how long they will work.

This method must be authenticated.

URL http://feed.fm/api/v2/access_token
Parameters
ttl_seconds Number of seconds from creation of the access token that the token will be valid. Defaults to 86400 (= 24 hours).
Error Codes

Only the generic error codes

Response

A token/secret pair.

Sample Response

{
  "success" : true,
  "access_token" : {
    "token" : "1234123412341234123412341234123412341244",
    "secret" : "1234123412341234123412341234123412341244"
  }
}
                

DEL access_token/:token

Description

Revokes a set of credentials created with POST /access_token

This method must be authenticated.

URL http://feed.fm/api/v2/access_token/:token
Parameters
token "token" value returned from a call to POST /access_token
Error Codes

Only the generic error codes

Response

Success code

Sample Response after a call to POST /access_token/123412341234123412341234:

{
  "success" : true
}
                

Client registration

To enforce DMCA playback rules and for general statistics, all clients must have a unique client device id that should be requested once and stored permanently.

POST client

Description

Return a unique identifier for this client device. Only a single identifier should reside on any device and should be shared among all users of the device. This identifier is required for retrieving new songs for playback and is used to enforce DMCA playback rules regarding song repetition.

This request must be authenticated.

URL http://feed.fm/api/v2/client
Parameters

None.

Error Codes

In addition to the generic error codes, there are:

Error Code HTTP Status Code Description
19 403 The client's IP address does not map to one in the United States, and so cannot play music
Response

A unique string identifier that can be used on the current client device.

Sample Response

{
  "success" : true,
  "client_id" : "1234-1234-1234-1234"
}
                

Placements

Placements are sources of music. A Placement may have one or more Stations associated with it that music can be played from. Management of placements is done via the web interface, so any resources in the API are for querying information about a placement.

GET placement

Description

Retrieves details about the default placement for the app identified by the credentials passed in.

This method must be authenticated.

URL http://feed.fm/api/v2/placement
Parameters

None.

Error Codes

Only the generic error codes.

Response

A JSON object with details about the default placement and stations in it.

Sample Response

{
    "success": true,
    "placement": {
      "id": "123",
      "name": "Epic Placement"
    },
    "stations": [
      {
        "id": "456",
        "name": "Station One"
      },
      {
        "id": "789",
        "name": "Station Two"
      }
    ]
}
                

GET placement/:id

Description

Retrieves details about the given placement.

This method must be authenticated.

URL http://feed.fm/api/v2/placement/:id
Parameters
id The id of the placement we're interested in.
Error Codes

Only the generic error codes.

Response

A JSON object with details about the given placement and the stations in it.

Sample Response

{
    "success": true,
    "placement": {
      "id": "123",
      "name": "Epic Placement"
    },
    "stations": [
      {
        "id": "456",
        "name": "Station One"
      },
      {
        "id": "789",
        "name": "Station Two"
      }
    ]
}
                

GET placement/:id/station

Description

Retrieves the list of stations associated with the given placement. This can be used to tune in to a specific station within a placement.

Normally you'd retrieve the list of stations for a given placement with the /placement or /placement/:id calls.

This method must be authenticated.

URL http://feed.fm/api/v2/placement/:id/station
Parameters
id The id of the placement we're retrieving stations from.
Error Codes

Only the generic error codes.

Response

A JSON array with 0 or more station objects is returned. Each station object consists of a string identifier and a name.

Sample Response

{
    "success": true,
    "stations": [
        {
            "id": "519",
            "name": "Top Hits"
        },
        {
            "id": "544",
            "name": "UK Garage"
        },
        {
            "id": "563",
            "name": "Smooth Jazz"
        },
        {
            "id": 576,
            "name": "Jeff's Classic Rock"
        }
    ]
}
                

Song retrieval and playback

Song playback requires the client to ask the server for something to play, followed by status updates to the server for auditing purposes.

POST play

Description

Retrieve a song for playback. This method retrieves all the meta-data about the song along with pointers to the actual song data itself.

Repeated calls to this method will return the same response until a successful 'POST play/:id/start' or 'POST play/:id/skip' call has been made to let the server know whether the song has begun playback not.

This method must be authenticated.

URL http://feed.fm/api/v2/play
Parameters
client_id The client identifier returned from the 'POST client' call.
placement_id (optional) The id of the placement from which music is drawn. If none is provided, the default placement for the passed in credentials is used.
station_id (optional) id of station in placement to draw music from. If no station id is provided the service will pick a default station.
formats (optional) Comma separated list of formats that the client is capable of playing. Available values are aac and mp3. The client can specify multiple values by separating them with commas. The server will use this information, along with the max_bitrate parameter, to pick a specific version of the audio file to return to the client.
max_bitrate (optional) This specifies the maximum bitrate for any audio files that are sent to the client. The value should be expressed as an integer and a multiple of 1,000. A value of "96" would imply a maximum bitrate of 96kb/s.
Error Codes

In addition to the generic error codes, there are:

Error Code HTTP Status Code Description
9 200 End of available music. There is no more music that can be played from this station.
19 403 The client's IP address does not map to one in the United States, and so cannot play music
20 403 Playback of this song has already started.
Response

The returned play object will contain track title, release title, and artist name information, along with a URL pointing to a file with audio data. The encoding of the audio data will be presented as one of 'aac', 'he-aac', or 'mp3'.

The URL to the audio data should be considered time sensitve. If it isn't used within the next 30 minutes, the URL will expire and return 404 not found.

Sample Response

{
  "success": true,
  "play": {
    "id": "27555",
    "station": {
      "id": "599",
      "name": "East Bay"
    },
    "audio_file": {
      "id": "665",
      "duration_in_seconds": "300",
      "track": {
          "id": "15224887",
          "title": "3030"
      },
      "release": {
          "id": "1483477",
          "title": "Deltron 3030"
      },
      "artist": {
          "id": "766824",
          "name": "Del the Funky Homosapien"
      },
      "codec": "aac",
      "bitrate": "128",
      "url": "http://feed.fm/audiofile-665-original.aac"
    }
  }
}
                

POST play/:id/start

Description

Inform the server that the user has started playing a song. This call must be made as soon as the client starts playing the song returned from a 'POST play' call.

Immediately after this call is made, and before a 'POST play/:id/skip' or 'POST play/:id/complete' call has been made, the client may make another call to 'POST play' to queue up the next song for playback.

This method must be authenticated.

URL http://feed.fm/api/v2/play/:id/start
Parameters
id The id of the play that has begun playback.
Error Codes

Only the generic error codes.

Response

This method returns a boolean result value. If true, the user may skip this song. If false, the user should not be allowed to skip the current song and must hear it to completion before another song may be started. Note: if 'can_skip' returns false, the client may definitely not skip playback of this song, but if the 'can_skip' value returns true, the user still might not be able to skip the song (the client won't know until after calling 'POST /play/:id/skip' and getting the response code).

Sample Response

{
  "success" : true,
  "can_skip" : true
}
                

POST play/:id/elapse

Description

During song playback, this call may be made periodically to indicate how many seconds of playback have elapsed for the user. This call isn't required, but is useful for reporting. The 'seconds' value should never be greater than the full duration of the song and it should always measure time from the start of song playback (as opposed to elapsed time since the last 'elapse' call). Only the most recent value passed to this call is saved.

This method must be authenticated.

URL http://feed.fm/api/v2/play/:id/elapse
Parameters
id The id of the play that is being referenced.
seconds The number of seconds of playback that has elapsed, expressed as an integer or floating point number. This value should never be less than 0 and will always be capped by the server to be no more than the duration of the song.
Error Codes

Only the generic error codes.

Response

Sample Response

{
  "success" : true
}
                

POST play/:id/skip

Description

If the user wishes to skip the current song, this call should be made to inform the server and receive confirmation that the user can skip the call.

If this call returns a value of 'true' for 'success', then the client may stop playback of the current song and begin playing the next song retrieved from 'POST play'. The client should not make a call to 'POST play/:id/complete' for the song being skipped if the skip is successful.

If playback rules prohibit this song from being skipped, the response will have a 'success' value of 'false'. The user must listen to the song through to completion before the next play may begin.

This method must be authenticated.

URL http://feed.fm/api/v2/play/:id/skip
Parameters
id The id of the play that is being referenced.
seconds (optional) Elapsed seconds of music that the client has played
Error Codes

In addition to the generic error codes, there are:

Error Code HTTP Status Code Description
7 200 User has reached their skip limit and may not skip this song.
12 200 This play is not currently being played so we can't determine skippability.
Response

Unlike other resource calls, this method has no return value per se - it only successfully skips or not.

Sample Response

{
  "success" : true
}
                

POST play/:id/invalidate

Description

If the client application is unable to start a song returned from a 'POST play' call (the media file is missing or unexpectantly doesn't appear to work on the client platform), then this call may be used to inform the server and mark the play as invalid so a subsequent 'POST play' call doesn't return the same play.

This method should only be used when the client has technical difficulty playing a song. It should not be used for user-initiated skipping - the 'POST /play/:id/skip' should be used in that case.

This method must be authenticated.

URL http://feed.fm/api/v2/play/:id/invalidate
Parameters
id The id of the play that is being referenced.
Error Codes

Only the generic error codes.

Response

This method always returns a 'success' status of 'true'.

Sample Response

{
  "success" : true
}
                

POST play/:id/complete

Description

Inform the server that the given song has played to completion.

This method must be authenticated.

URL http://feed.fm/api/v2/play/:id/complete
Parameters
id The id of the play that is being referenced.
Error Codes

Only the generic error codes.

Response

Sample Response

{
  "success" : true
}