Radioplayer Developer Reference
Search Endpoints
Technical reference for Radioplayer partner integrations.
Search Endpoints
- /{countryCode}/metadata/api/v2/search
- /{countryCode}/metadata/api/v2/search/live
- /{countryCode}/metadata/api/v4/search/series
- /{countryCode}/metadata/api/v2/search/onDemand
- /{countryCode}/metadata/api/v2/search/services
Search Endpoints
/{countryCode}/metadata/api/v2/search
Description
This endpoint allows users to perform a search query for both live stations and on-demand episodes based on keywords, geographic location, and other parameters.
The results are filtered based on the client's access permissions and the provided country code.
Request Parameters
The request consists of a path parameter, a header parameter, and query parameters.
Path ParametersName| Type| Required| Description
---|---|---|--- countryCode| string| Yes| The country code used to filter search results.
Header ParametersName| Type| Required| Description
---|---|---|--- Radioplayer-Client| string| Yes| A unique identifier for the client making the request. The response will be filtered to include only content that the client has access to.
Query ParametersName| Type| Required| Description
---|---|---|--- query| string| No| The search term(s) provided by the user. If not specified, results will be random. sv| string| No| Search variant. Defaults to an empty string. rpId| string| No| The Radioplayer ID of a specific service or schedule. guid| string| No| Used for backward compatibility, but does not affect the search results. hl| boolean| No| Enables highlighting in search results. Default is false. hlNameFragSize| int| No| The fragment size for highlighting within names. hlDescFragSize| int| No| The fragment size for highlighting within descriptions. hlPre| string| No| A prefix string that is added before the highlighted text. hlPost| string| No| A suffix string that is added after the highlighted text. lon| float| No| Longitude of the user's geolocation. lat| float| No| Latitude of the user's geolocation. geo| boolean| No| Enables or disables geo-based suggestions. Defaults to true.
Notes
queryis optional. If not provided, results will be random.The following elements in the JSON response are maintained for backward compatibility with the previous version but are not used in the response of this version:
guidrpIdsvhlhlNameFragSizehlDescFragSizehlPrehlPost
- If
geois enabled (true) , the search will consider the latitude (lat) and longitude (lon) if provided. - The
Radioplayer-Clientis mandatory , and results are filtered based on client access permissions.
Response Format
The response consists of stations and on-demand episodes that match the search criteria.
Example Response
For a request such as:
/724/metadata/api/v2/search?query=sportA possible response is:
{
"results": [
{
"groupId": "EiTB MEDIA, S.A.U.",
"searchResults": [
{
"id": "620",
"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.",
"multimedia": [
{
"type": "logo_unrestricted",
"url": "https://assets.radioplayer.org/724/724620/600/600/l6qoq4tz.png",
"width": 600,
"height": 600,
"language": "es",
"mimeValue": "image/png",
"index": 2
},
{
"type": "logo_unrestricted",
"url": "https://assets.radioplayer.org/724/724620/288/162/l6qoq4vm.png",
"width": 288,
"height": 162,
"language": "es",
"mimeValue": "image/png",
"index": 8
}
],
"liveStreams": [
{
"player": "https://www.eitb.eus/multimedia/radioplayer1/radio-euskadi/index.html"
},
{
"audioStreams": [
{
"streamSource": {
"url": "https://eitb-euskadi.flumotion.com/eitb/radioeuskadi_low.mp3",
"mimeValue": "audio/mpeg"
},
"bitRate": {
"target": 48000,
"variable": false
}
}
]
},
{
"audioStreams": [
{
"streamSource": {
"url": "https://eitb-euskadi.flumotion.com/eitb/radioeuskadi.mp3",
"mimeValue": "audio/mpeg"
},
"bitRate": {
"target": 128000,
"variable": false
}
}
]
},
{
"audioStreams": [
{
"streamSource": {
"url": "https://eitb-euskadi.flumotion.com/eitb/radioeuskadi.mp3",
"mimeValue": "audio/mpeg"
},
"bitRate": {
"target": 128000,
"variable": false
}
}
]
},
{
"audioStreams": [
{
"streamSource": {
"url": "https://eitb-euskadi.flumotion.com/eitb/radioeuskadi_low.mp3",
"mimeValue": "audio/mpeg"
},
"bitRate": {
"target": 48000,
"variable": false
}
}
]
}
]
}
]
},
{
"groupId": "503_https://www.rtve.es/play/audios/raider-sport-3/raider-sport-3-panticosa-infinita/5503771/",
"searchResults": [
{
"id": "503",
"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",
"longDescriptions": [
{
"value": "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",
"language": "es"
}
],
"onDemandStreams": [
{
"player": "https://www.rtve.es/play/audios/raider-sport-3/raider-sport-3-panticosa-infinita/5503771/",
"audioStreams": [
{
"streamSource": {
"url": "https://ztnr.rtve.es/ztnr/5503771.mp3",
"mimeValue": "audio/mpeg"
},
"bitRate": {
"target": 0,
"variable": false
}
}
],
"duration": 445000,
"availableStart": "2020-02-06T07:27:00Z",
"availableStop": "2025-02-12T00:30:34.686000Z"
}
],
"series": {
"id": "9510"
},
"odId": "0cedc487b08cab2696c9bb9b635b496e2702b56c89cf692bd19bf27608dfecfd",
"serviceName": "Radio 3",
"multimedia": [
{
"type": "logo_unrestricted",
"url": "https://img2.rtve.es/imagenes/raider-sport-3/1661520190855.jpg",
"width": 1400,
"height": 1400,
"language": "es",
"mimeValue": "",
"index": 0
}
],
"alphanumericKey": "r",
"mediumNames": [
{
"value": "Raider Sport 3 -",
"language": "es"
}
],
"longNames": [
{
"value": "Raider Sport 3 - Panticosa infinita - 06/02/2020",
"language": "es"
}
],
"links": [
{
"url": "https://ztnr.rtve.es/ztnr/5503771.mp3",
"mimeValue": "audio/mpeg"
}
],
"genres": []
}
]
}
]
}/{countryCode}/metadata/api/v2/search/live
Description
This endpoint allows users to search for live radio stations based on a query term, country code, and additional parameters such as geographic location and client ID.
The results are filtered based on the client's access permissions and the provided country code.
Request Parameters
The request consists of a path parameter, a header parameter, and query parameters.
Path ParametersName| Type| Required| Description
---|---|---|--- countryCode| string| Yes| The country code used to filter search results.
Header ParametersName| Type| Required| Description
---|---|---|--- Radioplayer-Client| string| Yes| A unique identifier for the client making the request. The response will be filtered to include only content that the client has access to.
Query ParametersName| Type| Required| Description
---|---|---|--- query| string| No| The search term(s) provided by the user. If not specified, results will be random. sv| string| No| Search variant. Defaults to an empty string. rpId| string| No| The Radioplayer ID of a specific service or schedule. guid| string| No| Used for backward compatibility, but does not affect the search results. hl| boolean| No| Enables highlighting in search results. Default is false. hlNameFragSize| int| No| The fragment size for highlighting within names. hlDescFragSize| int| No| The fragment size for highlighting within descriptions. hlPre| string| No| A prefix string that is added before the highlighted text. hlPost| string| No| A suffix string that is added after the highlighted text. lon| float| No| Longitude of the user's geolocation. lat| float| No| Latitude of the user's geolocation. geo| boolean| No| Enables or disables geo-based suggestions. Defaults to true.
Notes
The following elements in the JSON response are maintained for backward compatibility with the previous version but are not used in the response of this version:
guidrpIdsvhlhlNameFragSizehlDescFragSizehlPrehlPost
- Query Parameter
queryis optional. If not provided, results will be random. - If
geois enabled (true) , the search will consider the latitude (lat) and longitude (lon) if provided. - Results are grouped by
groupId, which represents a broadcaster or content provider. - The
Radioplayer-Clientis mandatory , and results are filtered based on client access permissions.
Response Format
The response consists of a list of live radio stations that match the search criteria, grouped by broadcaster.
Example Response
For a request such as:
/578/metadata/api/v2/search/live?query=rock&geo=true&latitude=41.902783&longitude=12.496365A truncated response containing a single element is shown below:
{
"results":[
{
"groupId":"Romsdals Budstikke AS",
"searchResults":[
{
"id":"109",
"name":"1FM Rock",
"description":"Vi tar pulsen på jazzen og Rosenes by og rocker Romsdal! ",
"multimedia":[
{
"type":"logo_unrestricted",
"url":"https://assets.radioplayer.org/578/578109/600/600/lh0c8pwj.png",
"width":600,
"height":600,
"language":"no",
"mimeValue":"image/png",
"index":2
},
{
"type":"logo_unrestricted",
"url":"https://assets.radioplayer.org/578/578109/288/162/lh0c8px7.png",
"width":288,
"height":162,
"language":"no",
"mimeValue":"image/png",
"index":8
}
],
"liveStreams":[
{
"player":"https://consoles.radioplayer.cloud/578109/index.html"
},
{
"audioStreams":[
{
"streamSource":{
"url":"https://lyd.1fm.no/1fmrock_hq",
"mimeValue":"audio/mpeg"
},
"bitRate":{
"target":192000,
"variable":false
}
}
]
},
{
"audioStreams":[
{
"streamSource":{
"url":"https://lyd.1fm.no/1fmrock_mq",
"mimeValue":"audio/mpeg"
},
"bitRate":{
"target":128000,
"variable":false
}
}
]
},
{
"audioStreams":[
{
"streamSource":{
"url":"https://lyd.1fm.no/1fmrock_lq",
"mimeValue":"audio/mpeg"
},
"bitRate":{
"target":96000,
"variable":false
}
}
]
}
]
}
]
}
]
}/{countryCode}/metadata/api/v4/search/series
Description
This endpoint allows users to search for podcast series based on a query term and country code. The API returns a list of podcast series that match the search criteria.
The results are filtered based on the client's access permissions and the provided country code.
Request Parameters
The request consists of a path parameter, a header parameter, and multiple query parameters.
Path ParametersName| Type| Required| Description
---|---|---|--- countryCode| string| Yes| The country code used to filter search results.
Header ParametersName| Type| Required| Description
---|---|---|--- Radioplayer-Client| string| Yes| A unique identifier for the client making the request. The response will be filtered to include only content that the client has access to.
Query ParametersName| Type| Required| Description
---|---|---|--- query| string| No| The search term(s) provided by the user. If not specified, results will be random. sv| string| No| Search variant, defaults to an empty string. rpId| string| No| The Radioplayer ID of a specific service or schedule. guid| string| No| Used for backward compatibility, but does not affect the search results. hl| bool| No| Enable highlighting in search results. hlNameFragSize| int| No| Fragment size to highlight for name field. hlDescFragSize| int| No| Fragment size to highlight for description field. hlPre| string| No| String to append at the start of the highlighted area. hlPost| string| No| String to append at the end of the highlighted area. lon| float| No| Longitude of the user’s geolocation. lat| float| No| Latitude of the user’s geolocation. geo| bool| No| Enable or disable geo-location-based suggestions, defaults to true.
Notes
As with previous endpoints, the following elements are included for backward compatibility but are not used in this version:
guidrpIdsvhlhlNameFragSizehlDescFragSizehlPrehlPost
- If
queryis not provided, random podcast series are returned based oncountryCode. - The
Radioplayer-Clientheader is mandatory , and results are filtered based on client access permissions.
Response Format
The response consists of a list of podcast series that match the search query, including metadata.
Example Response
For a request such as:
/826/metadata/api/v4/search/series?query=bbcA possible response (truncated at two elements) is:
{
"header":{
"numberFound":30,
"start":0,
"returned":30
},
"series":[
{
"id":"8499",
"name":"BBC Music Introducing Mixtape",
"description":"An hour of fresh new tunes from BBC Music Introducing handpicked by Emily Pilbeam each week in the early hours of Monday morning.",
"alphanumericKey":"b",
"service":{
"id":"347",
"name":"BBC Radio 6 Music"
},
"image":{
"url":"http://ichef.bbci.co.uk/images/ic/3000x3000/p0d7j1yy.jpg",
"width":1400,
"height":1400,
"language":"en",
"mimeValue":"image/jpeg",
"index":0,
"mediaType":"logo_unrestricted"
},
"genre":[
]
},
{
"id":"8074",
"name":"BBC Proms Music Guide",
"description":"In this set of free downloads, BBC Radio 3 presenters introduce a key composer and work featured in BBC Prom concerts.",
"alphanumericKey":"b",
"service":{
"id":"343",
"name":"BBC Radio 3"
},
"image":{
"url":"http://ichef.bbci.co.uk/images/ic/3000x3000/p02r965s.jpg",
"width":1400,
"height":1400,
"language":"en",
"mimeValue":"image/jpeg",
"index":0,
"mediaType":"logo_unrestricted"
},
"genre":[
{
"href":"3.6.1",
"name":"Classical music",
"type":"main"
}
]
}
]
}/{countryCode}/metadata/api/v2/search/onDemand
Description
This endpoint allows users to search for on-demand episodes based on a query term and country code. The API returns a list of episodes that match the search criteria , including metadata such as descriptions, multimedia, and streaming details.
The results are filtered based on the client's access permissions and the provided country code.
Request Parameters
The request consists of a path parameter, a header parameter, and multiple query parameters.
Path ParametersName| Type| Required| Description
---|---|---|--- countryCode| string| Yes| The country code used to filter search results.
Header ParametersName| Type| Required| Description
---|---|---|--- Radioplayer-Client| string| Yes| A unique identifier for the client making the request. The response will be filtered to include only content that the client has access to.
Query ParametersName| Type| Required| Description
---|---|---|--- query| string| No| The search term(s) provided by the user. If not specified, results will be random. sv| string| No| Search variant, defaults to an empty string. rpId| string| No| The Radioplayer ID of a specific service or schedule. guid| string| No| Used for backward compatibility, but does not affect the search results. hl| bool| No| Enable highlighting in search results. hlNameFragSize| int| No| Fragment size to highlight for name field. hlDescFragSize| int| No| Fragment size to highlight for description field. hlPre| string| No| String to append at the start of the highlighted area. hlPost| string| No| String to append at the end of the highlighted area. lon| float| No| Longitude of the user’s geolocation. lat| float| No| Latitude of the user’s geolocation. geo| bool| No| Enable or disable geo-location-based suggestions, defaults to true.
Notes
Similar to other search endpoints, the following elements are included for backward compatibility but are not used in this version:
guidrpIdsvhlhlNameFragSizehlDescFragSizehlPrehlPost
- If
queryis not provided, random episodes are returned based oncountryCode. - The
Radioplayer-Clientheader is mandatory , and results are filtered based on client access permissions.
Response Format
The response consists of a list of on-demand episodes that match the search query.
Example Response
For a request such as:
/826/metadata/api/v2/search/ondemand?query=rock&geo=true&latitude=51.521129&longitude=-0.16768A truncated response containing a single element is shown below:
{
"results":[
{
"groupId":"381_https://www.boomradiouk.com/radioplayer/boom-rock/od/items/60s-rock-with-roger-day-26th-january/",
"searchResults":[
{
"id":"381",
"name":"'60s Rock - with Roger Day",
"description":"The old pirate plays Rock from the decade of his radio debut",
"longDescriptions":[
{
"value":"The old pirate plays Rock from the decade of his radio debut",
"language":"en"
}
],
"onDemandStreams":[
{
"player":"https://www.boomradiouk.com/radioplayer/boom-rock/od/items/60s-rock-with-roger-day-26th-january/",
"audioStreams":[
{
"streamSource":{
"url":"https://aod.sharp-stream.com/content/boom_rock/storage/1737893188-60s_rock_with_roger_day.mp3?aw_0_1st.ri=sharpstream&aw_0_1st.organization=sharpstream&awEpisodeId=1bc0c05e-a4de-4c64-809c-5576f7755ff2&awCollectionId=boom_rock-standalone&providerId=boom_ro",
"mimeValue":"audio/mpeg"
},
"bitRate":{
"target":128000,
"variable":false
}
}
],
"duration":7500000,
"availableStart":"2025-01-26T12:05:00Z",
"availableStop":"2025-02-02T12:05:00Z"
}
],
"series":{
"id":"16667"
},
"odId":"f522a7fda7c4505a1581d2e53c8fe3dedc1769a3cf50d718c4023a86d4b1a6be",
"serviceName":"Boom Rock - from Boom Radio",
"multimedia":[
{
"type":"logo_unrestricted",
"url":"https://mmo.aiircdn.com/cdn-cgi/image/width=1400,height=1400,fit=cover/460/640b23851f669.jpg",
"width":1400,
"height":1400,
"language":"en",
"mimeValue":"",
"index":0
}
],
"alphanumericKey":"#",
"mediumNames":[
{
"value":"'60s Rock - with",
"language":"en"
}
],
"longNames":[
{
"value":"'60s Rock - with Roger Day",
"language":"en"
}
],
"links":[
{
"url":"https://aod.sharp-stream.com/content/boom_rock/storage/1737893188-60s_rock_with_roger_day.mp3?aw_0_1st.ri=sharpstream&aw_0_1st.organization=sharpstream&awEpisodeId=1bc0c05e-a4de-4c64-809c-5576f7755ff2&awCollectionId=boom_rock-standalone&providerId=boom_ro",
"mimeValue":"audio/mpeg"
}
],
"genres":[
]
}
]
}
]
}/{countryCode}/metadata/api/v2/search/services
Description
This endpoint allows users to search for live radio services (stations) based on a query term and country code. The API returns a list of station IDs that match the search criteria.
The results are filtered based on the client's access permissions and the provided country code.
Request Parameters
The request consists of a path parameter, a header parameter, and query parameters.
Path ParametersName| Type| Required| Description
---|---|---|--- countryCode| string| Yes| The country code used to filter search results.
Header ParametersName| Type| Required| Description
---|---|---|--- Radioplayer-Client| string| Yes| A unique identifier for the client making the request. The response will be filtered to include only content that the client has access to.
Query ParametersName| Type| Required| Description
---|---|---|--- query| string| No| The search term(s) provided by the user. If not specified, results will be random. rpId| string| No| The Radioplayer ID of a specific service or schedule. guid| string| No| Used for backward compatibility, but does not affect the search results.
Notes
- For backward compatibility, the
guidandrpIdelements are included but are not used in this version. - If
queryis not provided, random station IDs are returned based oncountryCode. - The
Radioplayer-Clientheader is mandatory , and results are filtered based on client access permissions.
Response Format
The response consists of a list of station RPUIDs that match the search query.
Example Response
For a request such as:
/380/metadata/api/v2/search/services?query=rtlA possible response is:
{
"services": [
"380102",
"380202",
"380201",
"380200",
"380197",
"380198",
"380199",
"380203",
"380224"
]
}