Radioplayer

Developer Reference

 Back
v4 · Current

Radioplayer Developer Reference

v4

Technical reference for Radioplayer partner integrations.

Version
Current
Document type
API reference
Audience
Radioplayer partner engineering teams

QueryProxy v4 Endpoints

/{countryCode}/qp/v4/recommend

Description

This endpoint returns a list of trending radio stations for a given country. The response is wrapped in a JSONP-style callback if specified.

Request Parameters

The request consists of:

  1. Path Parameters _(required in the URL path)_
  2. Query Parameters _(optional query parameters sent in the URL string)_

Path ParametersName| Type| Required| Description

---|---|---|--- countryCode| string| Yes| The country code used to filter trending stations.

Query ParametersName| Type| Required| Description

---|---|---|--- callback| string| No| A function name to wrap the JSON response for JSONP-style responses (used in legacy browsers). If not provided, callback is used by default.

Example Request (Query Parameters)
GET /724/qp/v4/recommend?callback=myCallback

Response Format

The response contains a list of trending radio stations formatted for JSONP.

Sample Response
myCallback({
        "recommendations":[
        {
            "type":"SERVICE",
            "rpId":"169",
            "serviceName":"COPE",
            "imageUrl":"https://assets.radioplayer.org/724/724169/600/600/kyer3tes.png",
            "consoleUrl":"https://consoles.radioplayer.cloud/724169/index.html",
            "factors":[
            "Trending"
            ]
        }
        ]
    })

Notes

Description

This endpoint allows users to search for both live radio stations and on-demand episodes using a query term. The search results are filtered based on the client's access permissions and the provided country code.

Request Parameters

The request consists of query parameters (sent in the URL query string).

Query ParametersName| Type| Required| Description

---|---|---|--- query| string| No| The user-provided search terms. If not specified, the response will return random results filtered by countryCode. callback| string| No| The JSONP callback function name for wrapping the response. Defaults to callback. countryCode| string| Yes| The country code used to filter results. This parameter is required.

Example Request (Query Parameters)
GET /qp/v4/search?countryCode=380&query=rock&callback=myCallback

Response Format

The response consists of radio stations and on-demand episodes that match the search query, formatted in a combined structure.

Sample Response
myCallback({
        "responseStatus": "SUCCESS",
        "total": 32,
        "results": {
            "1": {
                "groupID": "EiTB MEDIA, S.A.U.",
                "results": {
                    "1": {
                        "type": "SI",
                        "rpId": "620",
                        "serviceName": "Radio Euskadi",
                        "name": "Radio Euskadi",
                        "description": "Radio Euskadi es la cadena en castellano de Eusko Irratia, la radio pública vasca. Emisora de marcado carácter informativo, concebida como un servicio público, abierta a la sociedad y que, desde la cercanía al oyente, ofrece información y entretenimiento las 24 horas del día. Información cercana, desde el mismo lugar, y lejana, aportando para ello la visión \"glocal\" de los temas.  Fiel reflejo de la pluralidad de la sociedad vasca, Radio Euskadi aporta espacios para el encuentro, el diálogo y la reflexión serena.",
                        "imageUrl": "https://assets.radioplayer.org/724/724620/600/600/l6qoq4tz.png",
                        "consoleUrl": "https://www.eitb.eus/multimedia/radioplayer1/radio-euskadi/index.html"
                    },
                    "2": {
                        "type": "SI",
                        "rpId": "622",
                        "serviceName": "Gaztea",
                        "name": "Gaztea",
                        "description": "Gaztea Irratia musika ona eta entretenimendu hobea eskeintzen duen irrati musikala da. Gazteei zuzendutako katea, 24 orduz euskaraz emititzen du. Goizeko lehen ordutik entretenimendua eta musika ardatz duen magazinak astintzen ditu entzuleak. Eta iluntzean, beste horrenbeste, egunaren bilduma umoretsua osatuz. BItartean, eguneko garaiko tarteetan musika hoberena eskeintzen du. Baina ez da irrati formula arrunta. Munduko Hit-ak eta arrakastak zein diren jakin nahi baldin baduzu, eta Euskal Herriko punta-puntako taldeen azken diskoen berri jakin nahi baldin baduzu, Gaztea da zure irratia.",
                        "imageUrl": "https://assets.radioplayer.org/724/724622/600/600/kyesbfci.png",
                        "consoleUrl": "https://www.eitb.eus/multimedia/radioplayer1/gaztea/index.html"
                    }
                }
            },
            // ...
            "3": {
                "groupID": "0cedc487b08cab2696c9bb9b635b496e2702b56c89cf692bd19bf27608dfecfd_9510",
                "results": {
                    "1": {
                        "type": "OD",
                        "rpId": "503",
                        "serviceName": "Radio 3",
                        "name": "Raider Sport 3 - Panticosa infinita - 06/02/2020",
                        "description": "Desde un escenario de picos de más de 3.000 metros, que ayuda a que el entorno se llene de amantes de los deportes de aventura.Escuchar audio",
                        "imageUrl": "https://img2.rtve.es/imagenes/raider-sport-3/1661520190855.jpg",
                        "consoleUrl": "http://www.rtve.es/radioplayer/emisoras/rne3",
                        "odStartTime": "1580974020.0",
                        "odStopTime": "1738918080.614",
                        "startTime": "1580974020.0",
                        "stopTime": "1738918080.614",
                        "odId": "0cedc487b08cab2696c9bb9b635b496e2702b56c89cf692bd19bf27608dfecfd",
                        "seriesId": "9510"
                    }
                }
            }
        }
    })

Notes

/{countryCode}/qp/v4/search/live

Description

This endpoint allows users to search for live radio stations within a specified country based on a search query.

Request Parameters

The request consists of query parameters (sent in the URL query string).

Query ParametersName| Type| Required| Description

---|---|---|--- query| string| No| The user-provided search terms. If not specified, the API returns random results filtered by countryCode. callback| string| No| The name of the callback function for JSON-P response formatting. If not provided, the default is "callback". countryCode| string| Yes| The country code used to filter search results.

Example Request (Query Parameters)
GET /380/qp/v4/search/live?query=sport&callback=myCallback

Response Format

The response returns radio stations that match the search terms within the specified country, formatted as a JSON-P response.

Sample Response
myCallback({
        "responseStatus":"SUCCESS",
        "total":1,
        "results":{
            "1":{
                "groupID":"Rai - Radiotelevisione Italiana Spa",
                "results":{
                    "1":{
                        "type":"SI",
                        "rpId":"188",
                        "serviceName":"RAI Gr Parlamento",
                        "name":"RAI GrParlamento",
                        "description":"",
                        "imageUrl":"https://assets.radioplayer.org/380/380188/600/600/l455msn3.png",
                        "consoleUrl":"https://www.raiplayradio.it/grparlamento/"
                    },
                    "2":{
                        "type":"SI",
                        "rpId":"101",
                        "serviceName":"RAI Radio 1",
                        "name":"RAI Radio 1",
                        "description":"",
                        "imageUrl":"https://assets.radioplayer.org/380/380101/600/600/kyctxalx.png",
                        "consoleUrl":"https://www.raiplayradio.it/radio1/"
                    }
                }
            }
        }
    })

Notes

/{countryCode}/qp/v4/search/od

Description

This endpoint allows users to search for on-demand (OD) content (episodes and podcasts) within a specified country based on a search query.

Request Parameters

The request consists of query parameters (sent in the URL query string).

Query ParametersName| Type| Required| Description

---|---|---|--- query| string| No| The user-provided search terms. If not specified, the API returns random results filtered by countryCode. callback| string| No| The name of the callback function for JSON-P response formatting. If not provided, the default is "callback". countryCode| string| Yes| The country code used to filter search results.

Example Request (Query Parameters)
GET /380/qp/v4/search/od?query=podcast&callback=myCallback

Response Format

The response returns on-demand episodes and podcasts that match the search terms within the specified country, formatted as a JSON-P response.

Sample Response
myCallback({
        "responseStatus":"SUCCESS",
        "total":5,
        "results":{
            "1":{
                "groupID":"dd521e6945202e8692c3ff054ef267dff5c0d9c5b0f672b640bb91c883fdb6f8_8276",
                "results":{
                    "1":{
                        "type":"OD",
                        "rpId":"344",
                        "serviceName":"BBC Radio 4",
                        "name":"BBC plans, IPSO, X Factor",
                        "description":"The BBC outlined its vision this week for a more open and more distinctive BBC that would involve working more closely with arts and science institutions and local news services. Steve Hewlett hears from the BBC's Director of Strategy James Purnell about the plans.A year after the Independent Press Standards Organisation (IPSO) was set up, a survey for the pressure group Hacked Off found over sixty percent of people lacked confidence in the regulator, which is backed by the majority of the UK's major newspaper publishers. A letter in this week's Guardian signed by eleven people who had taken a complaint to IPSO denounced the regulator as a sham body. Steve speaks to Evan Harris, Joint Executive Director Hacked Off, about its concerns, and to Matt Tee, Chief Executive of IPSO, about the criticisms, and gets his reflections on the last year and what's next for the regulator.The X Factor has been criticised for scouting for contestants with a pre-existing professional pedigree rather than relying solely on genuine walk-in applicants. The show has also come under attack for contestants giving humble back stories, like this week's \"I work on a farm\", that do not reflect their true previous success in showbiz. So has the well of UK talent dried up? Should the X Factor format be put out of its misery? Is the audience too jaded, too cynical and too small to care anyway? Steve hears from Kevin O'Sullivan, the Sunday Mirror's TV columnist.Producer: Dianne McGregor.",
                        "imageUrl":"http://ichef.bbci.co.uk/images/ic/3000x3000/p0hp32y8.jpg",
                        "consoleUrl":"https://www.bbc.co.uk/sounds/player/bbc_radio_fourfm?partner=org.radioplayer",
                        "odStartTime":"1441816140.0",
                        "odStopTime":"1738820851.526",
                        "startTime":"1441816140.0",
                        "stopTime":"1738820851.526",
                        "odId":"dd521e6945202e8692c3ff054ef267dff5c0d9c5b0f672b640bb91c883fdb6f8",
                        "seriesId":"8276"
                    }
                }
            }
        }
    })

Notes

/{countryCode}/qp/v4/suggest

Description

This endpoint provides search suggestions for live radio stations and on-demand episodes (podcasts). The suggestions are generated based on the user's query and are filtered by country code.

The response includes:

Request Parameters

The request consists of query parameters (sent in the URL query string).

Query ParametersName| Type| Required| Description

---|---|---|--- query| string| No| The user-provided search terms. If not specified, the API returns general keyword suggestions. callback| string| No| The name of the callback function for JSON-P response formatting. If not provided, the default is "callback". countryCode| string| Yes| The country code used to filter search results.

Example Request (Query Parameters)
GET /380/qp/v4/suggest?query=rock&callback=myCallback

Response Format

The response provides search suggestions for radio stations and on-demand episodes.

Sample Response

myCallback({
        "keywords":[
        {
            "name":"94,3 RS2 - Berlin"
        },
        {
            "name":"JAM FM Berlin Christmas"
        },
        {
            "name":"bigFM Berlin"
        }
        ],
        "live":[
        {
            "rpId":"2654",
            "serviceName":"94,3 RS2 - Berlin",
            "description":"94,3 RS2 Berlin - Dein Lieblingsmix!",
            "imageUrl":"https://assets.radioplayer.org/276/2762654/600/600/lm4v7cye.png",
            "url":"https://webradio.rs2.de/berlin/"
        },
        {
            "rpId":"2123",
            "serviceName":"JAM FM Berlin Christmas",
            "description":"JAM FM Berlin Christmas ist dein modernes und urbanes Weihnachtsradio. Dein perfekter Christmas Mix aus Klassikern und modernen Weihnachtssongs.",
            "imageUrl":"https://assets.radioplayer.org/276/2762123/600/600/lpwkht95.jpeg",
            "url":"https://consoles.radioplayer.cloud/2762123/index.html"
        }
        ],
        "onDemand":[
        {
            "rpId":"1661",
            "imageUrl":"https://cdn-img.nrjaudio.fm/podcasts/de/5/1984/cfb97f95-6200-4541-a25a-9ec173d7e693.jpg",
            "startTime":"2019-02-14T17:22:30",
            "name":"Hangover Berlin Spezial",
            "description":"Valentinstags Singles spezial! Für alle, die heute alleine spielen müssen!",
            "serviceName":"ENERGY Berlin - HIT MUSIC ONLY !",
            "url":"https://www.energy.de/radioplayer/digital/index.html"
        }
        ]
    })

Notes