Radioplayer

Authentication

You should authenticate your programmatic station/schedule submissions with a username/key combination encoded using BasicAuth. Radioplayer will provide you with these details.

Option A - Easy upgrade of legacy implementations (pre-2022)

Radioplayer Cloud supports the legacy DAB EPG formats (v1.2 + Radioplayer extensions) to match the Classic platform. You can continue to send us your station information in those formats and we will process your data as before.

Each station on Radioplayer has a new identifier, called an RPUID - replacing the former RPID. To save converting the RPID to a RPUID for each station, and to maintain backwards compatibility, you can use the ‘Classic Style’ ingest paths which have the country code embedded. For example, for UK stations the Now Playing Ingest endpoint URL would be as follows (see below):

• https://np-ingest.radioplayer.cloud/826/ 

This is the 'path of least resistance' for most stations - as only a change of username/password and the path would be required.

When sending Radioplayer information in the legacy formats, please use the following endpoints:

This allows you to continue to submit information with RPIDs and Radioplayer will translate them into RPUIDs.

For example, to send a station update for a UK station, one would use the following URL

• https://core-ingest.radioplayer.cloud/latest/826/v1/si

If you were to use cURL to submit a PI file to an ingest endpoint one would submit it as follows:

curl -u youruser:yourpassword -X POST --header "Content-Type:text/xml;charset=UTF-8" -d @20220715_611_PI.xml https://core-ingest.radioplayer.cloud/latest/826/v1/pi

Upgrading the 'Now Playing' Simple HTTP endpoint

Please use the new V2 Now Playing endpoint to submit your Now Playing information.

Now Playing (NP)

The API allows clients to submit a more concise form of Now Playing data that is easier to manage - as an alternative to sending PE.

Now Playing updates should be submitted to:

• https://np-ingest.radioplayer.cloud/826/

The territory ID is the ISO 3166 Country Code which is 826 for the UK, and is embedded in the URL in the example shown above.

The request parameters are as follows:

Note that to maintain backwards compatibility with Radioplayer 'Classic', to submit a now playing event using a territory RPID rather than a Cloud RPUID, you must use the parameter rpId - note the capitalisation - for the request to be successfully authenticated. 

To send it using the RP Classic style endpoint, use the following:

curl -u yourusername:yourpassword -v -X POST "https://np-ingest.radioplayer.cloud/826?rpId=YOUR_RPID&startTime=2022-07-04T15:00:00&duration=600&title=SONGTITLE&artist=ARTIST"

The table below shows for each endpoint what the old UK one was and what the new Cloud endpoint is:

Option B - Building a New Integration

Station and Schedule Updates

Use the new endpoints which require the RPUID to be submitted in every request. This is useful if you have a single Ingest account which needs to work across multiple countries (e.g. you are a metadata provider with a global footprint).

Please note:

• These endpoints support the legacy DAB EPG formats and the v3.1.1 version of the DAB EPG specification - although it is not mandatory to use the new spec. However, as this URL does not include the country code, all station identifiers must be updated to use the relevant rpuid even if you are sending us information in the legacy format.
  
  

• Data should be POSTed to these endpoints. The XML should be the request body.

Using the V2 Now Playing Simple HTTPS endpoint in new integrations

Now Playing updates should be submitted to:

• https://np-ingest.radioplayer.cloud

A template example of how you could post this data using the commonly found 'curl' command line utility follows:

curl -u yourusername:yourpassword -v -X POST "https://np-ingest.radioplayer.cloud?rpuid=YOUR_RPUID&startTime=2022-07-04T15:00:00&duration=600&title=SONGTITLE&artist=ARTIST"

Glossary

• API - an application programming interface (API) is a method for two or more computer applications to communicate with each other.
  
  
• Country code - a standard three-digit code that uniquely identifies a country.
  
  
• cURL - cURL is an application that provides used for transferring data across networks using various protocols.
  
  
• Endpoint - an endpoint is one end of a communication channel. When an API interacts with another system, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service.
  
  
• Metadata - a set of data that describes and gives information about other data. In Radioplayer, metadata often refers to Station Information (SI), Programme Information (PI), Programme Events (PE), Off-Schedule / On Demand (OD), and Now Playing (NP).
  
  
• RPID - the distinct Radioplayer ID that previously identified a station in the old 'Classic' Radioplayer platform.
  

• RPUID - the globally unique Radioplayer Unique ID that identifies a station in the new Radioplayer platform. The RPUID consists an RPID combined with the ISO 3166 country code.
  
  For example, below the RPUID consists of the three-letter country code (for the UK: 826) plus an RPID of several digits and this can be seen when you log into my.radioplayer.org:
  

The station's RPUID can also be seen when logging into my.radioplayer.org and navigating to the Station Overview: