API Reference

Retrieve schedules for one or more stations

/stations/{rpuids}/schedule

Returns scheduling information for up to five station objects. Results are returned by station.

Endpoint

Base URL: https://api.radioplayer.org/v2/stations/{rpuids}/schedule

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

Get station schedule for stations

/v2/stations/3722,372101/schedule
PATH PARAMETER VALUE
{rpuids} Specifies one or more station objects by their rpuid, which can be requested using a comma separated list

Query Parameters






Get station schedule with from/to date, page and size

/v2/stations/8261004,826100/schedule?from=2020-06-09T15%3A27%3A33%2B0000&to=2020-06-11T15%3A27%3A33%2B0000&page=1&size=7
QUERY PARAMETER VALUE
from The start time of the schedule in ISO8601 format.

Optional. If the from and to parameters are omitted, then the API returns the station’s schedule for the next 24 hours starting from the nearest hour before the current time.

Note: if using the from parameter, it is necessary to also apply the to parameter.

to Optional. The end time of the schedule in ISO8601 format.

If from and to parameters are omitted, then the API returns the station’s schedule for the next 24 hours starting from the nearest hour before the current time.

Note: if using the to parameter, it is necessary to also apply the from parameter.

page Optional. If the results are paginated, this specifies which page is returned.
size Optional. This specifies the maximum number of results to return in the response.

Response

When successful, the HTTP status code in the response header is 200 OK.

An array of nested ids identifying schedules are returned for each specified rpuid.

These are returned in JSON format (or on special request, XML supported by the RadioDNS schema).

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

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.

Example Response Body

{
    "data": [
        {
        "data": [
            {
            "id": "sp:/crid://planetradio.co.uk;dab/abr2020-03-27T13:00:00",
            "locations": [
                {
                "scheduledStart": "2020-03-27T13:00:00Z",
                "scheduledStop": "2020-03-27T16:00:00Z"
                }
            ],
            "description": "Danielle Perry brings you the No Repeat Guarantee - loads of great music and you'll never hear the same song twice. Text now on 81215 (50p + n/wk chrg) or tweet @AbsoluteRadio",
            "name": "No Repeat Guarantee"
            },
            {
            "id": "sp:/crid://planetradio.co.uk;dab/abr2020-03-27T16:00:00",
            "locations": [
                {
                "scheduledStart": "2020-03-27T16:00:00Z",
                "scheduledStop": "2020-03-27T19:00:00Z"
                }
            ],
            "description": "The Hometime show, brought to you by Andy Bush & Richie Firth. 3 hours of nonsense presented by 2 confused dads. Apologies in advance.",
            "name": "Hometime with Bush & Richie"
            },
            {
            "id": "sp:/crid://planetradio.co.uk;dab/abr2020-03-27T19:00:00",
            "locations": [
                {
                "scheduledStart": "2020-03-27T19:00:00Z",
                "scheduledStop": "2020-03-27T22:00:00Z"
                }
            ],
            "description": "Claire Sturgess is tarting your Friday night with a bang, playing you all the undisputed classics of the 1980s. Get your leg warmers on and frizz that hair! Tweet @AbsoluteRadio",
            "name": "Absolute 80s Greatest Hits"
            },
            {
            "id": "sp:/crid://planetradio.co.uk;dab/abr2020-03-27T22:00:00",
            "locations": [
                {
                "scheduledStart": "2020-03-27T22:00:00Z",
                "scheduledStop": "2020-03-28T04:00:00Z"
                }
            ],
            "description": "Dan Noble plays the best songs from across the Absolute Radio network. From 60s to 00s, there'll be tracks you've not heard for ages!",
            "name": "Through The Decades"
            },
            {
            "id": "sp:/crid://planetradio.co.uk;dab/abr2020-03-28T04:00:00",
            "locations": [
                {
                "scheduledStart": "2020-03-28T04:00:00Z",
                "scheduledStop": "2020-03-28T08:00:00Z"
                }
            ],
            "description": "Early start today? No bother because Chris Martin is here to kick-start your morning with some brilliant music.",
            "name": "Early Breakfast"
            },
            {
            "id": "sp:/crid://planetradio.co.uk;dab/abr2020-03-28T08:00:00",
            "locations": [
                {
                "scheduledStart": "2020-03-28T08:00:00Z",
                "scheduledStop": "2020-03-28T11:00:00Z"
                }
            ],
            "description": "Frank, Emily and Alun are here to make you smile on a Saturday morning. Stick the kettle on and join them for a cuppa.",
            "name": "The Frank Skinner Show"
            },
            {
            "id": "sp:/crid://planetradio.co.uk;dab/abr2020-03-28T11:00:00",
            "locations": [
                {
                "scheduledStart": "2020-03-28T11:00:00Z",
                "scheduledStop": "2020-03-28T14:00:00Z"
                }
            ],
            "description": "Whatever you're doing with your weekend, Sarah Champion has your playlist sorted with brilliant music both new and old.",
            "name": "Sarah Champion"
            }
        ],
        "meta": {
            "country": "826",
            "rpuid": "826100",
            "paginated": true,
            "nesting": false,
            "fromCache": false,
            "cacheExpiresAt": 1585318585827,
            "count": 7,
            "pageSize": 7,
            "lastPage": true,
            "firstPage": true,
            "totalPages": 1,
            "pageNumber": 0
        }
        }
    ],
    "meta": {
        "nesting": true,
        "paginated": false,
        "dataType": "schedule",
        "count": 1,
        "fromCache": false,
        "cacheExpiresAt": null
    }
}

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

The possible meta field values for this endpoint are:

FIELD VALUE
paginated Optional, Boolean. Sets how or if results are grouped into pages.

This value will be set to true for each station object returned. Each station is an object with its own meta object, so this results in nested pagination.

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 true.

For more information on nesting, see the API Documentation index.
dataType Object type returned by the request. In this case it is schedule.
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
id String. A unique identifier which identifies a programme within the schedule
locations Array. An array of schedule start and end dates which indicate when the programme is expected to be broadcast
locations
↳ scheduledStart
Date. RFC3339-formatted datestamp describing the date and time when the programme is likely to be broadcast
locations
↳ scheduledStop
Date. RFC3339-formatted datestamp describing the date and time when the programme will end.
description Optional, String. A short (128 char) description of the programme
name String. The name of the programme
multimedia Array. Where provided, this is an array of visual assets such as episode or series images depicting the programme. There may be none, one or many images available
multimedia
↳ url
URL. The URL of the visual asset.
multimedia
↳ mimeValue
String. A string describing the MIME type of the visual asset such as image/jpeg
multimedia
↳ width
Integer. The width of the visual asset in pixels.
multimedia
↳ height
Integer. The height of the visual asset in pixels.
multimedia
↳ index
Integer. Where multiple images are provided, this value indicates the image to attempt to use first, where the lower the value, the higher the priority.