Overview

URL
Authentication
Request and Response Format
Charset (UTF-8)
Pagination
Localization
Rate Limiting
Command Line Tools Used in Examples

URL

All API access is over HTTPS, and accessed from api.spreaker.com. The current API version is v2, so each API URL will start with:

https://api.spreaker.com/v2/

Authentication

Spreaker APIs use OAuth2 to handle user authentication. See Authentication to understand how you can obtain a valid OAuth2 token to perform API requests on behalf of the user.

In general, all PUT, POST and DELETE requests MUST be authenticated in order to succeed. However, GET requests do not require authentication unless otherwise documented.

Once you have a valid token, you can use it in two different ways:

#### OAuth2 Token (sent in a header)

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/me

OAuth2 Token (sent as a parameter)

curl https://api.spreaker.com/v2/me?oauth2_access_token=OAUTH-TOKEN

Authenticating with invalid credentials will return as 401 Unauthorized.

Request and Response Format

All data is received as JSON and wrapped in a response property.

Example: Successful Response

{
    "response": {
        "user": {
            "user_id": 1,
            "fullname": "Marco Pracucci",
            "site_url": "https://www.spreaker.com/user/marco"
        }
    }
}

If there are any errors, you will receive the most appropriate 4xx or 5xx HTTP status code and the response will include an error object containing one or more error messages.

Example: Error Response

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

Timestamps

All timestamps are in YYYY-MM-DD HH:MM:SS format and in the UTC timezone, except where otherwise stated.

Charset (UTF-8)

Spreaker APIs currently support only UTF-8 charset encoding. Please, make sure your request body data is encoded in UTF-8.

Pagination

Requests that return multiple items are paginated. The responses will contain items, an array of JSON objects, and next_url, the URL of the next “page” of data.

By default, each “page” contains 50 items. You can customize this value using the limit query parameter to request up to 100 items.

Each API can use a different parameter to select a “page”. That way the response will contain the next_url property. You should use that particular URL for loading more content instead of constructing your own.

Example

curl https://api.spreaker.com/v2/users/8114541/shows?limit=3

Response

{
  "response": {
    "items": [
      {
        "show_id": 1396918,
        ...
      },
      {
        "show_id": 1433865,
        ...
      },
      {
        "show_id": 1634369,
        ...
      }
    ],
    "next_url": "https://api.spreaker.com/v2/users/8114541/shows?offset=3&limit=3"
  }
}

Localization

Some Spreaker APIs return content that can be localized, passing a supported culture via the c parameter.

Example

The GET /v2/show-categories returns all available show categories in English by default, but you can get Italian category name translations by invoking:

curl https://api.spreaker.com/v2/show-categories?c=it_IT

Supported cultures

en_US (default)
it_IT
es_ES

Rate Limiting

Spreaker APIs adopt a rate limiting policy. We kindly ask you to play nicely with our APIs, and you should never hit the rate limit. In case you do hit the limit, your IP address will be temporarily blacklisted and each subsequent API request will result in the 429 Too Many Requests response.

Command Line Tools Used in Examples

Looking at the examples you can find the following command-line tools:

curl
json