Developers ยป Simple API
close

Simple API Overview

The official.fm Simple API provides a RESTful way to access resources such as tracks, users, and playlists. All requests are simple GET requests that return JSON, JSONP or XML responses.

Authentication is done via a token passed as an HTTP parameter to every request. The Simple API is read-only. Use the Advanced API if you want to upload tracks, vote, edit metadata, etc.

URL structure

Using the API is making GET requests to URLs that look like this:

http://api.official.fm/user/scoopdeville/tracks?limit=1&format=json&key=XXX

And getting responses that look like this:

JSON

[
  {
    title: "dancin on your grave prod. Scoop Deville",
    artist_string: "Get Busy Committee ft. Brevi",
    id: 151426,
    plays_count: 916
  }
]

XML

<tracks>
  <track>
    <title>dancin on your grave prod. Scoop Deville</title>
    <artist_string>Get Busy Committee ft. Brevi</artist_string>
    <id>151426</id>
    <plays_count>916</plays_count>
  </track>
</tracks>


When paginate option is available, just add /paginate at the end of URL:

http://api.official.fm/user/scoopdeville/tracks/paginate?limit=1&format=json&key=XXX

And getting responses that look like this:

JSON

{
  total:100,
  page:1,
  per_page:20,
  current:20,
  tracks: 
  [
    {
      title: "dancin on your grave prod. Scoop Deville",
      artist_string: "Get Busy Committee ft. Brevi",
      id: 151426,
      plays_count: 916
    }
  ]
}

XML

<tracks total="100" page="1" per_page=20"" current="20">
  <track>
    <title>dancin on your grave prod. Scoop Deville</title>
    <artist_string>Get Busy Committee ft. Brevi</artist_string>
    <id>151426</id>
    <plays_count>916</plays_count>
  </track>
</tracks>

Each application has its own application key. If you don't have one yet, register now!

See endpoints for a comprehensive list of valid request URLs, and their possible responses

Parameters

Sometimes an API url accepts additional parameters, such as genre, or api_embed_codes.
The key parameter is the only parameter required for all requests.

Parameters in a GET request are added like that:

http://api.official.fm/?param1=value1&param2=value2&param3=value3

The following parameters are accepted by all requests:

Example values Description
key AkMbo298SDFg28dJ297k Mandatory application key. (required)
format json, xml Desired format for server responses (Default: XML)
callback handle_response JavaScript callback to use in a JSONP response.
Use only with format=json

API Console

The best way to experiment try a few requests in our awesome API console powered by apigee.
top