1. Overview

Spreaker provides a public REST web service (API) that you can use to develop widgets and applications that interacts with Spreaker.

Getting started with API

The following API end points are supported:

Spreaker API allows to access and modify most of data on Spreaker (if you've right privileges). For example, you can easily read public user profile by doing the following easy request:
curl http://api.spreaker.com/user/1

The response is jsonTo check if a response is a success or an error, you should check the response status code:
2xx: success
4xx: client error (if you retry the same request with the same exact parameters you will get the same error)
5xx: server error (if you retry the same request with the same exact parameters it could work)

Success response format

The success response always contains a response object, whose content can be of three different types:
  • record: a single entity that contains various information (eg. user, show, radio, ...)
  • collection: a list of records
  • pager: a special data type used for data pagination (details later)

Example (record):
{"response": {"time": {"epoch": 1295955160, "date":"2011-01-25 11:32:40" }}}

Error response format

All the errors thrown by the Spreaker API, are in the same format. The response object contains an error object with the following properties:
  • code: the response status code
  • messages: an array of strings

Example:
{response: {error: { messages: [ "The provided API uri is unknown" ], code: 404 }}}


I18n

Spreaker API internationalization and localization. The default culture for an authenticated request is read from authenticated user preferences, while it fallbacks to en_US culture for unauthenticated requests. You can override the default culture, adding GET parameter c=<culture code> to your requests.

Example:
GET /user/1?c=it_IT

Spreaker API responses contain two HTTP headers that specify the response language and culture:

  • Content-Language: contains the response language eg. it
  • X-Spreaker-Culturecontains the response culture eg. it_IT

Timestamp

Timestamps returned from Spreaker APIs are in UTC (unless otherwise stated) and always specified in ISO format (YYYY-MM-DD HH:MM:SS).

Pager

Some requests to the Spreaker API can return a large amount of data, for example if you want to fetch all the messages sent to a popular radio.

In this cases, the API does not return a collection, but a pager, a special data type that permit to navigate large results set. The structure is very simple:

{"response":{
    "pager":{
        "current_page":1,
        "first_page":1,
        "last_page":4,
        "results_count":"39",
        "results":[
]
}}}



 PropertyType 
Description 
current_page 
integer 
The number of the current page
first_pageinteger 
The number of the first page available 
last_page
integer 
The number of the last page available
results_countintegerThe total number of available results
results
array The collection of results

Implementation notes:
  • If you try to fetch a page number greater than the last page, the API returns the last page itself.
  • If you try to fetch a page number less than the first page, the API returns the first page itself.

If you need to move forward and backward in the result set, every request that returns a pager, support two additional query parameters:

NameDescription
Type 
Required 
page
The page number
Integerfalse, default 1
max_per_pageThe maximum number of records per page
Integerfalse, default 10


Rate Limit

We don't like limits, but sometimes it's necessary. To be completely fair, we currently don't have any limit in terms of maximum number of API calls per IP / hour. However, we've some limits on the number of concurrent calls per IP and temporary blacklist in case we detect a flood of requests. Please, use our API responsibly. Thank you.