Introduction to the Radioplayer WRAPI JAVASCRIPT SDK

WRAPI JavaScript SDK Quick start

Before you can make calls to the WRAPI services, you first must obtain a key and and keyId from Radioplayer.

Required setup steps

Radioplayer WRAPI JAVASCRIPT SDK Installation

The package is intended to be run on a node application. To install it, type this command in a Terminal window or a command prompt:

npm install wrapi-javascript-sdk

yarn add wrapi-javascript-sdk

Configure the SDK

Configuring the Radioplayer WRAPI JAVASCRIPT SDK

After you install the SDK, you must make the SDK available to your app and configure your environment. Configuration details include your client ID and secret for your app and an optional wrapi endpoint override.

const wrapi = require("wrapi-javascript-sdk").default;

const wp = new wrapi({ keyId: "your key id", key: "your key" });

How to use the SDK

How to use the Radioplayer WRAPI JAVASCRIPT SDK .

The following WRAPI endpoints can be used with the SDK:

/stations
/stations/{rpuids}
/stations/{rpuids}/onair
/stations/{rpuids}/schedule
/ondemand
/ondemand/{odids}
/recommendations
/categories

The endpoints must be called with the correct request parameters as described in Request Param Types). Note that some parameter combinations are required, for instance to perform a search for stations by a search term, you must also provide a country code. See the Radioplayer WRAPI API docs for more details.

const params = { ... };

const stations = await wp.getStations(params);
const stationsOnAir = await wp.getOnAir(params);
const stationsSchedule = await wp.getSchedule(params);
const stationOndemand = await wp.getStationOndemand(params);
const ondemand = await wp.getOnDemand(params);
const recommendations = await wp.getRecommendations(params);
const categories = await wp.getCategories(params);

The expected data return types can be found here: Return types

Wrapi - Class description

Class: Wrapi

Hierarchy

Wrapi

Index

Constructors

constructor

Properties

baseURL
keys

Methods

Constructors

constructor

+ new Wrapi(__namedParameters: object): Wrapi

Parameters:

▪ __namedParameters: object

Name	Type	Default
`baseURL`	string \| URL	"https://api.radioplayer.org/v2"
`key`	string	-
`keyId`	string	-

Returns: Wrapi

Properties

`Private` baseURL

• baseURL: string | URL

`Private` keys

• keys: object

The keys (a pem file and a corresponding key ID) can be obtained from Radioplayer by emailing contact@radioplayer.co.uk

Type declaration:

key: string
keyId: string

Methods

`Private` createRequest

▸ createRequest(requestUrl: string): object

Parameters:

Name	Type
`requestUrl`	string

Returns: object

keys(): object
- key: string
- keyId: string
url: string = requestUrl

getCategories

▸ getCategories(params: CategoriesParams): Promise‹CategoryResponse›

Returns a list of category names and hrefs for ondemand or live data.

Parameters:

Name	Type
`params`	CategoriesParams

Returns: Promise‹CategoryResponse›

getOnAir

▸ getOnAir(params: OnAirParams): Promise‹OnAirResponse›

Retrieve on air, now-playing events, such as programs or songs. You can specify one or multiple stations to request information from, and can optionally retrieve any events that are playing next.

Parameters:

Name	Type
`params`	OnAirParams

Returns: Promise‹OnAirResponse›

getOnDemand

▸ getOnDemand(params: OdParams): Promise‹StationOnDemandResponse›

Retrieves ondemand items. These can be as a result of a text search, a search-by-country, or a search-by-category. Also retrieves information about particular, specified ondemand items, indicated by the odIds parameter.

Parameters:

Name	Type
`params`	OdParams

Returns: Promise‹StationOnDemandResponse›

getRecommendation

▸ getRecommendation(params: RecommendationParams): Promise‹RecommendationResponse›

Retrieve recommendations of stations and (optionally) ondemand items. A default request will just return recommended stations; an optional onDemand paramter can be included in the body to include onDemand items in the response.

Parameters:

Name	Type
`params`	RecommendationParams

Returns: Promise‹RecommendationResponse›

getSchedule

▸ getSchedule(params: StationScheduleParams): Promise‹ScheduleResponse›

Retrieve station schedules. You can specify one or multiple stations to request information from, up to a maximum of five rpuids per request. Results will be organised by station, and each station's results will be paginated.

Parameters:

Name	Type
`params`	StationScheduleParams

Returns: Promise‹ScheduleResponse›

getStationOndemand

▸ getStationOndemand(params: StationOndemandParams): Promise‹StationOnDemandResponse›

Returns a paginated subset of on demand items for a given station. Results are returned in chronological order, the most recent first. You may also provide the station rpuid for the series you are requesting.

Parameters:

Name	Type
`params`	StationOndemandParams

Returns: Promise‹StationOnDemandResponse›

getStations

▸ getStations(params: StationParams | GetStationsByRpUidsParams): Promise‹StationResponse›

Retrieve information about stations. An entire list of stations can be returned, or query parameters can be added to filter the results. You may also use the same endpoint to retrieve station information for one or more stations.

Parameters:

Name	Type
`params`	StationParams \| GetStationsByRpUidsParams

Returns: Promise‹StationResponse›

Interface: KeyAndId

Hierarchy

KeyAndId

Index

Properties

key
keyId

Properties

key

• key: string

keyId

• keyId: string

Return types

KeyAndId

`/stations`

StationResponse StationEntry
Phonetics

`/stations/{rpuids}`

Interface: StationResponse

StationResponse

Hierarchy

BaseResponse

↳ StationResponse

Index

Properties

data

• data: StationEntry[]

Overrides BaseResponse.data

`Optional` error

• error? : undefined | object

Inherited from BaseResponse.error

meta

• meta: BaseMeta

Overrides BaseResponse.meta

Interface: StationEntry

Hierarchy

StationEntry

↳ RecommendedStation

Index

Properties

alphanumericKey

• alphanumericKey: string

The letter/number to indicate where in an alphabetic list this station should be placed

bearers

• bearers: Array‹object›

An array of bearer IDs and information.

country

• country: string

ISO number code of the station's country.

description

• description: string

Station description.

liveStreams

• liveStreams: Stream[]

Stream urls and information for this station.

multimedia

• multimedia: MultiMedia[]

Station assets, typically logo images.

name

• name: string

Station name

phoneticInputs

• phoneticInputs: Phonetics[]

Any phonetic SSML tags or spellings that can be used to help voice controlled devices recognise a station name as said by an end user

phoneticOutputs

• phoneticOutputs: Phonetics[]

Any phonetic SSML tags or spellings that can be used to help voice controlled devices speak/pronounce a station name if required

rpuid

• rpuid: string

Unique identifier representing a specific station. Unique across all countries.

socialIds

• socialIds: string[]

The ids of any linked social media accounts this station has.

Interface: MultiMedia

Hierarchy

MultiMedia

Index

Properties

height

• height: number

The natural height of the resource

language

• language: string

Resource language

mimeValue

• mimeValue: string

The resource mime type.

type

• type: string | null

The type of resource

url

• url: string

The resource url.

width

• width: number

The natural width of the resource

Interface: Bearer

Hierarchy

Bearer

Index

Properties

cost

• cost: number

Cost is a relative measure of the 'cost' of accessing a station over a given bearer. 'Cost' is contextual: it could represent latency, cost of link, processing cost, etc. Lower is better.

id

• id: string

The id of the bearer

`Optional` mimeValue

• mimeValue? : undefined | string

The mime value of this particular bearer

Interface: Stream

Hierarchy

Stream

Index

Properties

audioFormat

• audioFormat: string

availableStart

• availableStart: Date

Only for ondemand items: the date from which the on demand item is available

availableStop

• availableStop: Date

Only for ondemand items: the date until which the on demand item is available

bitrate

• bitrate: object

Details about the stream bit rate

Type declaration:

target: number
variable: boolean

streamRestriction

• streamRestriction: object

Type declaration:

relationship: "allow" | "deny"
value: string

streamSource

• streamSource: object

Type declaration:

mimeValue: string
url: string

Interface: Phonetics

Hierarchy

Phonetics

Index

Properties

`Optional` exclude

• exclude? : string[]

A list of any platforms that we know this phonetic record should be excluded from. For example, we know that SSML inputs are not supported on the Amazon Alexa, so any SSML inputs should include 'alexa' in this array

id

• id: string

A unique ID for the phonetic record

`Optional` type

• type? : undefined | string

Specifies whether the format of this phonetic spelling is SSML or a fuzzy, pidgin-English type spelling. Values will be ssml or pidgin

`Optional` value

• value? : undefined | string

The phonetic spelling/pronunciation of the station in question

Interface: StationOnDemandResponse

Hierarchy

BaseResponse

↳ StationOnDemandResponse

Index

Properties

data

• data: ODData[]

Overrides BaseResponse.data

`Optional` error

• error? : undefined | object

Inherited from BaseResponse.error

meta

• meta: PaginatedMeta

Overrides BaseResponse.meta

Interface: ODData

Hierarchy

ODData

↳ RecommendedOD

Index

Properties

country

• country: string

The country this show's station is in

description

• description: string

The description of the on demand item.

id

• id: string

A unique ID for the on demand item

liveStreams

• liveStreams: Stream[]

Stream urls and information for item.

multimedia

• multimedia: MultiMedia[]

Assets, typically show/album art images.

name

• name: string

The name of the on demand item.

rpuid

• rpuid: string

The station this show belongs to.

series

• series: object

The series this item is part of, if at all

Type declaration:

id: string

Interface: CategoryResponse

Hierarchy

BaseResponse

↳ CategoryResponse

Index

Properties

data

• data: CategoryData[]

Overrides BaseResponse.data

`Optional` error

• error? : undefined | object

Inherited from BaseResponse.error

meta

• meta: BaseMeta

Overrides BaseResponse.meta

Interface: CategoryData

Hierarchy

CategoryData

Index

Properties

href
name

Properties

href

• href: string

The href reference for the category

name

• name: string

The name of the category

Interface: OnAirResponse

Hierarchy

BaseResponse

↳ OnAirResponse

Index

Properties

data

• data: NestedData[]

Overrides BaseResponse.data

A collection of station's onair data. Even if only one station is requested, results will still be organised into an array of objects, each object containing an array of results for said station's onair information

`Optional` error

• error? : undefined | object

Inherited from BaseResponse.error

meta

• meta: BaseMeta

Overrides BaseResponse.meta

Interface: RecommendationData

Hierarchy

RecommendationData

↳ RecommendedStation

↳ RecommendedOD

Index

Properties

factors
type

Properties

factors

• factors: Factors[]

type

• type: "STATION" | "ONDEMAND"

Interface: RecommendationResponse

Hierarchy

BaseResponse

↳ RecommendationResponse

Index

Properties

data

• data: Array‹RecommendedStation | RecommendedOD›

Overrides BaseResponse.data

`Optional` error

• error? : undefined | object

Inherited from BaseResponse.error

meta

• meta: BaseMeta

Overrides BaseResponse.meta

Interface: RecommendedStation

Hierarchy

RecommendationData
StationEntry

↳ RecommendedStation

Index

Properties

alphanumericKey

• alphanumericKey: string

Inherited from StationEntry.alphanumericKey

The letter/number to indicate where in an alphabetic list this station should be placed

bearers

• bearers: Array‹object›

Inherited from StationEntry.bearers

An array of bearer IDs and information.

country

• country: string

Inherited from StationEntry.country

ISO number code of the station's country.

description

• description: string

Inherited from StationEntry.description

Station description.

factors

• factors: Factors[]

Inherited from RecommendationData.factors

liveStreams

• liveStreams: Stream[]

Inherited from StationEntry.liveStreams

Stream urls and information for this station.

multimedia

• multimedia: MultiMedia[]

Inherited from StationEntry.multimedia

Station assets, typically logo images.

name

• name: string

Inherited from StationEntry.name

Station name

phoneticInputs

• phoneticInputs: Phonetics[]

Inherited from StationEntry.phoneticInputs

Any phonetic SSML tags or spellings that can be used to help voice controlled devices recognise a station name as said by an end user

phoneticOutputs

• phoneticOutputs: Phonetics[]

Inherited from StationEntry.phoneticOutputs

Any phonetic SSML tags or spellings that can be used to help voice controlled devices speak/pronounce a station name if required

rpuid

• rpuid: string

Inherited from StationEntry.rpuid

Unique identifier representing a specific station. Unique across all countries.

socialIds

• socialIds: string[]

Inherited from StationEntry.socialIds

The ids of any linked social media accounts this station has.

type

• type: "STATION" | "ONDEMAND"

Inherited from RecommendationData.type

Interface: RecommendedOD

Hierarchy

RecommendationData
ODData

↳ RecommendedOD

Index

Properties

country

• country: string

Inherited from ODData.country

The country this show's station is in

description

• description: string

Inherited from ODData.description

The description of the on demand item.

factors

• factors: Factors[]

Inherited from RecommendationData.factors

id

• id: string

Inherited from ODData.id

A unique ID for the on demand item

liveStreams

• liveStreams: Stream[]

Inherited from ODData.liveStreams

Stream urls and information for item.

multimedia

• multimedia: MultiMedia[]

Inherited from ODData.multimedia

Assets, typically show/album art images.

name

• name: string

Inherited from ODData.name

The name of the on demand item.

rpuid

• rpuid: string

Inherited from ODData.rpuid

The station this show belongs to.

series

• series: object

Inherited from ODData.series

The series this item is part of, if at all

Type declaration:

id: string

type

• type: "STATION" | "ONDEMAND"

Inherited from RecommendationData.type

Interface: ScheduleResponse

Hierarchy

BaseResponse

↳ ScheduleResponse

Index

Properties

data

• data: NestedData[]

Overrides BaseResponse.data

A collection of station's schedules. Even if only one station is requested, results will still be organised into an array of objects, each object containing an array of results for said station's schedule information.

`Optional` error

• error? : undefined | object

Inherited from BaseResponse.error

meta

• meta: BaseMeta

Overrides BaseResponse.meta

NestedData

Interface: Collection

Hierarchy

Collection

Index

Properties

description

• description: string

The description of the item

id

• id: string

A unique ID for this item

location

• location: object

The scheduled start and stop times the item will be on air.

Type declaration:

scheduledStart: Date
scheduledStop: Date

mediaCredits

• mediaCredits: object

More detailed, formatted information about song or programme events

Type declaration:

role: "artist"
scheme: string
value: string

name

• name: string

The name of the item

Interface: BaseMeta

Hierarchy

BaseMeta

↳ PaginatedMeta

↳ OnAirMeta

Index

Properties

cacheExpiresAt

• cacheExpiresAt: number | null

When does the cache expire?

count

• count: number

How many items are there in the overall result data set.

dataType

Describes the data type returned

fromCache

• fromCache: boolean

Have cached values been returned?

nesting

• nesting: boolean

Indicates that data is nested into collections of items on a per-station basis

paginated

• paginated: boolean

Indicates whether the results in the corresponding data field are a paginated subset of all possible results

Interface: BaseResponse

All response types extend this - nothing should implement this directly

Hierarchy

BaseResponse

↳ StationResponse

↳ OnAirResponse

↳ ScheduleResponse

↳ StationOnDemandResponse

↳ RecommendationResponse

↳ CategoryResponse

Index

Properties

data

• data: Array‹object›

`Optional` error

• error? : undefined | object

Interface: OnAirMeta

Hierarchy

BaseMeta

↳ OnAirMeta

Index

Properties

cacheExpiresAt

• cacheExpiresAt: number | null

Inherited from BaseMeta.cacheExpiresAt

When does the cache expire?

count

• count: number

Inherited from BaseMeta.count

How many items are there in the overall result data set.

country

• country: string

dataType

Inherited from BaseMeta.dataType

Describes the data type returned

fromCache

• fromCache: boolean

Inherited from BaseMeta.fromCache

Have cached values been returned?

nesting

• nesting: boolean

Inherited from BaseMeta.nesting

Indicates that data is nested into collections of items on a per-station basis

paginated

• paginated: boolean

Inherited from BaseMeta.paginated

Indicates whether the results in the corresponding data field are a paginated subset of all possible results

rpuid

• rpuid: string

Interface: PaginatedMeta

Hierarchy

BaseMeta

↳ PaginatedMeta

↳ ScheduleMeta

Index

Properties

cacheExpiresAt

• cacheExpiresAt: number | null

Inherited from BaseMeta.cacheExpiresAt

When does the cache expire?

count

• count: number

Inherited from BaseMeta.count

How many items are there in the overall result data set.

dataType

Inherited from BaseMeta.dataType

Describes the data type returned

firstPage

• firstPage: boolean

For paginated data - is this the first page of available information?

fromCache

• fromCache: boolean

Inherited from BaseMeta.fromCache

Have cached values been returned?

lastPage

• lastPage: boolean

For paginated data - is this the last page of available information?

nesting

• nesting: boolean

Inherited from BaseMeta.nesting

Indicates that data is nested into collections of items on a per-station basis

pageNumber

• pageNumber: number

For paginated data - the current page of results. Starts at 0

pageSize

• pageSize: number

For paginated data - how many items will be returned per page of results.

paginated

• paginated: boolean

Inherited from BaseMeta.paginated

Indicates whether the results in the corresponding data field are a paginated subset of all possible results

totalPages

• totalPages: number

For paginated data - the total number of available pages of data.

Interface: ScheduleMeta

Hierarchy

↳ PaginatedMeta

↳ ScheduleMeta

Index

Properties

cacheExpiresAt

• cacheExpiresAt: number | null

Inherited from BaseMeta.cacheExpiresAt

When does the cache expire?

count

• count: number

Inherited from BaseMeta.count

How many items are there in the overall result data set.

country

• country: string

The subsets in this data array are organised into collections by station: this is the country the station is part of

dataType

Inherited from BaseMeta.dataType

Describes the data type returned

firstPage

• firstPage: boolean

Inherited from PaginatedMeta.firstPage

For paginated data - is this the first page of available information?

fromCache

• fromCache: boolean

Inherited from BaseMeta.fromCache

Have cached values been returned?

lastPage

• lastPage: boolean

Inherited from PaginatedMeta.lastPage

For paginated data - is this the last page of available information?

nesting

• nesting: boolean

Inherited from BaseMeta.nesting

Indicates that data is nested into collections of items on a per-station basis

pageNumber

• pageNumber: number

Inherited from PaginatedMeta.pageNumber

For paginated data - the current page of results. Starts at 0

pageSize

• pageSize: number

Inherited from PaginatedMeta.pageSize

For paginated data - how many items will be returned per page of results.

paginated

• paginated: boolean

Inherited from BaseMeta.paginated

Indicates whether the results in the corresponding data field are a paginated subset of all possible results

rpuid

• rpuid: string

The subsets in this data array are organised into collections by station: an rpuid will be included for reference to indicate which station the corresponding data array relates to

totalPages

• totalPages: number

Inherited from PaginatedMeta.totalPages

For paginated data - the total number of available pages of data.

Request param types

MakeSignedRequestParams

`/stations`

StationParams

`/stations/{rpuids}`

GetStationsByRpUidsParams

`/stations/{rpuids}/onair`

OnAirParams

`/stations/{rpuids}/schedule`

StationScheduleParams

`/stations/{rpuid}/ondemand` and `/stations/{rpuid}/ondemand/{seriesId}`

StationOndemandParams

`/ondemand and /ondemand/{odIds}`

OdParams

`/recommendations`

RecommendationParams

`/categories`

CategoriesParams

Interface: CategoriesParams

Hierarchy

CategoriesParams

Index

Properties

country
type

Properties

country

• country: string

Required. Three digit country ISO code used to specify from which Radioplayer region we want to receive category lists.

type

• type: "live" | "ondemand"

Required. Specifies whether you want live or ondemand data returned. These are the only two allowed values.

Interface: GetStationsByRpUidsParams

Hierarchy

GetStationsByRpUidsParams

Index

Properties

`Optional` include

• include? : StationIncludes[]

Limit the fields that are returned in each station object. An array of possible values

rpuids

• rpuids: string[]

Retrieves specific stations: an array of rpuid strings

Interface: MakeSignedRequestParams

Hierarchy

MakeSignedRequestParams

Index

Properties

keys

• keys: KeyAndId

`Optional` method

• method? : "GET" | "POST"

`Optional` requestBody

• requestBody? : undefined | string

url

• url: string | URL

Interface: OdParams

Hierarchy

OdParams

Index

Properties

`Optional` category

• category? : undefined | string

search for ondemand items by category. The category identifiers can be found by querying the categories endpoint, and using the returned href values (uri-encoded). Requires an additional country parameter to be included.

`Optional` country

• country? : undefined | string

Required if using the search or category parameters. A 3 digit country ISO code.

`Optional` odIds

• odIds? : string[]

Search for ondemand items by a comma separated string of ondemand IDs. Maximum 5 odIds per request.

`Optional` search

• search? : undefined | string

Search for on demand items with a uri-encoded search term - essentially a text search on show titles and descriptions. Requires an additional country parameter to be included.

Interface: OnAirParams

Hierarchy

OnAirParams

Index

Properties

next
rpuids

Properties

`Optional` next

• next? : undefined | false | true

A boolean to indicate if you would like your response to include information about the next scheduled events, as well as those currently on air. Defaults to false.

rpuids

• rpuids: string[]

Required. Specify the stations you would like onair information for, in a comma separated list of rpuids

Interface: RecommendationParams

Hierarchy

RecommendationParams

Index

Properties

`Optional` artistPlayCounts

• artistPlayCounts? : ArtistPlay[]

An array of objects each containing an artistName string, and a corresponding playCount integer. Used in conjunction with the MUSICMATCH parameter.

`Optional` country

• country? : undefined | string

Three digit country ISO code used to specify from which Radioplayer region we want to receive recommendations

`Optional` facebookArtists

• facebookArtists? : string[]

An array of artist names that when used in conjunction with the MUSICMATCH parameter can help tailor recommendations.

factors

• factors: Factors[]

What factors do you want to influence your recommendations? Multiple factors can be used. Possible values are "GEO", "TRENDING", "AFFINITY", and "MUSICMATCH"

`Optional` latitude

• latitude? : undefined | number

Recommendations can be tailored based on the user's location when the GEO factor is included - an optional latitude and longitude can be included in the body

`Optional` longitude

• longitude? : undefined | number

Recommendations can be tailored based on the user's location when the GEO factor is included - an optional latitude and longitude can be included in the body

`Optional` onDemand

• onDemand? : undefined | false | true

If true, on demand items will be included in the recommendations. Default is false.

`Optional` rpuid

• rpuid? : undefined | string

A station rpuid, typically the last listened or currently listened to station. This influences recommendations when the AFFINITY factor is included

Interface: StationOndemandParams

Hierarchy

StationOndemandParams

Index

Properties

`Optional` page

• page? : undefined | number

To specify a particular page of results, add this parameter to your query

rpuid

• rpuid: string

Required. Specify the station you would like on demand items to be returned for. Currently only one rpuid per request

`Optional` seriesId

• seriesId? : undefined | string

Required. Specify the series you would like on demand items to be returned for. Currently only one seriesId per request

`Optional` size

• size? : undefined | number

The number of results to return (per page)

Interface: StationParams

Hierarchy

StationParams

Index

Properties

`Optional` bearerId

• bearerId? : undefined | string

Search for a station based on a bearerId.

`Optional` country

• country? : undefined | string

Required if searching by geo, term or bearerId parameters. Otherwise an optional 3 digit country ISO code to limit the size and speed of requests. Recommended.

`Optional` geo

• geo? : number[]

Search for a station with a comma-separated array of latitude and longitude (eg [101,-97]).

`Optional` include

• include? : StationIncludes[]

Limit the fields that are returned in each station object. An array of possible values

`Optional` search

• search? : undefined | string

Search for a station with a uri-encoded search term.

`Optional` sort

• sort? : undefined | "alphanumericKey"

At the moment, the only supported sort order is 'alphanumericKey'

Interface: StationScheduleParams

Hierarchy

StationScheduleParams