API Reference

Return all stations

/stations

Returns all radio stations in the database, unless filtered by query parameters.

Results can be filtered by country, search terms, geolocation, and bearer IDs. You can also limit the number of fields returned for each station object by using the include parameter.

Endpoint

Base URL: https://api.radioplayer.org/v2/stations

Request Parameters

 Header Fields

To find out how to correctly construct authentication headers for the Radioplayer Partner API (WRAPI) please see the Authentication guide

 Path Parameters

PATH PARAMETER VALUE
stations Returns multiple station objects

Query Parameter


Station lookup

/v2/stations/372101?include=social,images

Lookup by Country Code

/v2/stations/?country=372

Lookup by bearer id

/v2/stations/?bearerId=dab%3Ace1%2Ec1a7%2Ecbe5%2E0

Search lookup

/v2/stations/?country=372&search=talent

Geo lookup

/v2/stations/?country=826&geo=52%2E234494,0%2E083882

Sorting

/v2/stations/sort=alphanumericKey
QUERY PARAMETER VALUE
include Optional. Specifies which fields are returned by the request for each station object, defined by a comma separated list.

Available values are:
  • ids (rpuids are always returned whether specified or not)
  • detail (includes name, description and country)
  • bearers (includes bearerIds)
  • social (includes social ids)
  • streams (includes livestream URLs)
  • images (includes any URLs for images, such as logos).
If include is not applied, all fields will be returned for the station object.
country Optional, unless using search or geo. An ISO 3166 numeric country code. When applied only returns results from the specified country. Recommended parameter.
bearerId Optional. Id object from bearers array. Returns a specified bearerId object.

Cannot be used simultaneously with search or geo.
search Optional. Returns station objects containing a specified search string.

Requires a country parameter. Cannot be used simultaneously with bearerId or geo.
geo Optional. Returns station objects matching a specified geolocation value in latitude and longitude.

Requires a country parameter. Cannot be used simultaneously with bearerId or search.
sort Optional. Sorts returned results into alphanumeric order.

Response

Sample header

content-type: application/json; charset=utf-8
x-ratelimit-limit: 300000
x-ratelimit-remaining: 285030
x-ratelimit-reset: 1585699200

When successful, the HTTP status code in the response header is 200 OK. One or more station objects are returned in JSON format (or on special request, XML supported by the RadioDNS schema).

If there is an error, the header returns an error status code

The WRAPI also includes information about your monthly request quota in the returned header:

This includes information on:

  • Your total monthly quota
  • How many requests you have remaining for the month
  • When the quota will be reset, given as a UNIX timestamp.

The returned response body consists of a meta and data object.

The possible meta field values for this endpoint are:

Sample Response

    {
        "data": [
            {
            "name": "98FM Throwback",
            "description": "98FM Throwback, your destination for non-stop nineties and noughties ",
            "liveStreams": [
                {
                "streamSource": {
                    "url": "https://stream.audioxi.com/THROWAAC?aw_1st_stream=RP",
                    "mimeValue": "audio/aac"
                },
                "bitRate": {
                    "target": 48000
                }
                },
                {
                "streamSource": {
                    "url": "https://stream.audioxi.com/THROWAAC?aw_1st_stream=RP",
                    "mimeValue": "audio/aac"
                },
                "bitRate": {
                    "target": 64000
                }
                }
            ],
            "alphanumericKey": "#",
            "multimedia": [
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_600x600_2018-11-22-16-45-02-721.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 600,
                "height": 600
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_86x48_2018-08-31-11-00-00-384.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 86,
                "height": 48
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_288x162_2018-08-31-11-00-00-477.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 288,
                "height": 162
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_128x128_2018-11-30-10-15-03-200.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 128,
                "height": 128
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_1920x1080_2018-11-22-16-45-02-925.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 1920,
                "height": 1080
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_74x41_2018-08-31-11-00-00-262.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 74,
                "height": 41
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_160x90_2018-08-31-11-00-00-411.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 160,
                "height": 90
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_320x240_2018-11-30-10-15-03-719.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 320,
                "height": 240
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_112x32_2018-11-30-10-15-03-792.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 112,
                "height": 32
                },
                {
                "url": "http://ierpimagecache.s3.amazonaws.com/image/101_32x32_2018-11-30-10-15-03-823.png",
                "mimeValue": "image/png",
                "language": "en",
                "width": 32,
                "height": 32
                }
            ],
            "country": "372",
            "rpuid": "372101",
            "bearers": [],
            "phoneticInputs": [],
            "phoneticOutputs": []
            },

            ...

        ],

        "meta": {
            "nesting": false,
            "paginated": false,
            "dataType": "stations",
            "count": 61,
            "fromCache": true,
            "cacheExpiresAt": 1585299658094
        }
    }
FIELD VALUE
paginated Optional, Boolean. Sets how or if results are grouped into pages.

For more information on pagination, see the API Documentation index.
nesting Optional, Boolean. Indicates whether full data objects are nested within other objects.

For this endpoint this value is always set to false.

For more information on nesting, see the API Documentation index.
dataType Object type returned by the request. In this case it is stations.
count Optional, string. A number describing how many items are in the data set.
fromCache Optional, Boolean. Indicates whether this data came from cached data.

For more information on caching, please see the API Documentation index.
cacheExpiresAt Optional. UNIX timestamp indicating when the cache will expire.

For more information on caching, please see the API Documentation index.

The possible data field values for this endpoint are:

FIELD VALUE
name String. The full name of the radio station
description String. A description relating to the station. Typically a slogan or strapline under 128 characters.
livestream Array. An array containing one or many live streaming assets.
streamSource Array. An array describing a single audio stream.
↳ url URL. The URL of the live stream resource.
mimeValue String. The MIME type of the stream which indicates the stream codec and format.
bitrate
↳ target
Integer. A number, in bits per second, indicating the bitrate of the stream.
socialIds Array, optional. An array of one or more social media identifiers
↳ type Constant. Can be ‘twitter’ or ‘facebook’
↳ uid String. The corresponding social media ID.
alphanumericKey String. Where a station is listed in an alphabetical list, this key indicates the letter of the alphabet under which the content should appear.
multimedia Array. An array of one of one or many visual assets (typically station logos)
↳ url String. URL of the image asset
↳ language String. Language of the image asset. Useful for image that may display lines of text
↳ type String, constant. This is always logo_unrestricted as per the DAB-EPG spec
↳ width Integer. The number of pixels representing the width of the image
↳ height Integer. The number of pixels representing the height of the image.
rpuid Integer. A unique identifier relating to the radio station that published the OD content
country Integer. ISO numeric country code of the station that published the OD content.
bearers Array, Optional. An array of broadcast transmission parameters. See Section 5 of ETSI TS102818 for details
↳ id String, URI. An individual broadcast bearer.
↳ cost Integer. The ‘cost’ of the bearer (see ETSI TS102818)
phoneticInputs Array, optional. An array of synonyms - typically alternative names for a station, or spellings to assist recognition by voice systems.
↳ id String. A unique identifier for the entry.
↳ type Constant. The type of phonetic schema used. Usually ‘pidgin’; ‘ssml’ also supported
↳ value String. The phonetic entry itself.
↳ exclude Array. An array of platforms which should disregard this entry. If empty, assume use by all voice platforms is allowed.
phoneticOutput Array, optional. An array of phonetics to assist voice systems with the correct pronunciation of a station name.
↳ id String. A unique identifier for the entry.
↳ type Constant. The type of phonetic schema in use. Either ‘pidgin’ or ‘ssml’
↳ value String. The value of the phonetic entry itself.
↳ exclude Array, optional. An array of platforms which should disregard this entry. If empty, assume use by all voice platforms is allowed.