Radioplayer Developer Reference

Search

Technical reference for Radioplayer partner integrations.

Version: Current
Document type: API reference
Audience: Radioplayer partner engineering teams

/{countryCode}/v1/search

/{countryCode}/v1/search

Description

Search for content (stations, podcasts, episodes) with optional geolocation and filtering capabilities.

Request Parameters

The request consists of a path parameter, a header parameter, and query parameters.

Path Parameters

Name	Type	Required	Description
`countryCode`	string	Yes	Country code to localize the search.

Query Parameters

Name	Type	Required	Default	Description
`collections`	list of strings	No	`['stations', 'podcasts', 'episodes']`	Specifies which content types to search in. Valid values are `stations`, `podcasts`, `episodes`.
`query`	string	No	`None`	The user-provided search term(s).
`geo`	boolean	No	`true`	Enable or disable geolocation-based suggestions.
`lat`	float	No	`None`	Latitude for geolocation (if `geo` is true).
`lon`	float	No	`None`	Longitude for geolocation (if `geo` is true).

Header Parameters

Name	Type	Required	Description
`client_id`	string	Yes	A unique client identifier.

Notes

The podcasts value in collections is internally mapped to podcast.
The endpoint uses StationFormatter, PodcastFormatter, and EpisodesFormatter to format respective data.
Geolocation is used only when geo is true and both lat and lon are provided.
Extensive logging is in place for debugging and monitoring.

Response Format

{
    "stations": [],
    "podcasts": [],
    "episodes": []
}

Example Response

For a request such as:

/826/v1/search?geo=true&lat=41.902783&lon=12.496365&query=sport&collections=stations&collections=podcasts&collections=episodes

A possible response is:

{
    "stations": [
    {
        "id": "12864",
        "rpuid": "8261188",
        "broadcasterGroupId": "102",
        "name": "Absolute Radio 70s",
        "liveStreams": {
            "player": "https://radioplayer.planetradio.co.uk/ab7",
            "audioStreams": [
            {
                "streamSource": {
                    "url": "https://stream-ar.hellorayo.co.uk/absolute70s.aac?direct=true&aw_0_1st.skey=1602676850",
                    "mimeValue": "audio/aac"
                },
                "audioFormat": "urn:mpeg:mpeg7:cs:AudioPresentationCS:2001:3",
                "bitRate": {
                    "target": 48000,
                    "variable": false
                }
            },
            {
                "streamSource": {
                    "url": "https://stream-ar.hellorayo.co.uk/absolute70shigh.aac?direct=true&aw_0_1st.skey=1602676850",
                    "mimeValue": "audio/aac"
                },
                "audioFormat": "urn:mpeg:mpeg7:cs:AudioPresentationCS:2001:3",
                "bitRate": {
                    "target": 128000,
                    "variable": false
                }
            }
            ]
        },
        "bearers": [
        {
            "id": "dab:ce1.c1c3.c1c2.0",
            "cost": "0",
            "mimeValue": "audio/mpeg"
        }
        ],
        "multimedia": [
        {
            "type": "logo_unrestricted",
            "url": "https://assets.radioplayer.org/826/8261188/600/600/mdfk5aui.png",
            "width": 600,
            "height": 600,
            "language": "en",
            "mimeValue": "image/png",
            "index": 2
        },
        {
            "type": "logo_unrestricted",
            "url": "https://assets.radioplayer.org/826/8261188/288/162/mdfk5auh.png",
            "width": 288,
            "height": 162,
            "language": "en",
            "mimeValue": "image/png",
            "index": 8
        }
        ],
        "alphanumerickey": "a",
        "appLinkConfiguration": {
            "applicationLogo": "",
            "applicationPackageId": "",
            "cls": "",
            "description": "",
            "name": "",
            "url": ""
        },
        "imageUrl": "https://assets.radioplayer.org/826/8261188/600/600/mdfk5aui.png",
        "consoleUrl": "https://radioplayer.planetradio.co.uk/ab7",
        "sortName": "Absolute 02",
        "description": "The decade of Blondie, Bowie & Queen",
        "shortName": "ab7",
        "mediumName": "Absolute Radio 7",
        "longName": "Absolute Radio 70s",
        "synonyms": [
        "absolute radio seventies",
        " absolute seventies"
        ],
        "geoFootprint": "",
        "countryName": "United Kingdom",
        "discoverability": "searchable",
        "status": "published",
        "frequencies": [],
        "genres": [
        {
            "href": "3.1.1",
            "name": "News, Sports and Talk",
            "type": "main"
        }
        ],
        "keywords": [],
        "language": "English",
        "phoneticInputs": [
        {
            "type": "pidgin",
            "value": "absolute radio seventies"
        },
        {
            "type": "pidgin",
            "value": " absolute seventies"
        }
        ],
        "phoneticOutputs": [
        {
            "type": "pidgin",
            "value": "Absolute Radio 70s"
        }
        ],
        "socialIds": [],
        "strapLine": "The decade of Blondie, Bowie & Queen",
        "targets": [
        "Amazon Echo",
        "Android",
        "Automotive",
        "Bose",
        "Chromecast",
        "Movistar",
        "Sonos",
        "Web",
        "iOS"
        ]
    }
    ],
    "podcasts": [
    {
        "id": "16682",
        "title": "'50s Vintage Charts",
        "url": "",
        "expiryDate": null,
        "imageUrl": "https://mmo.aiircdn.com/cdn-cgi/image/width=1400,height=1400,fit=cover/460/66c3d3d69b2ac.jpg",
        "totalEpisodes": 0,
        "stationRpuids": [
        "8261562"
        ],
        "description": "Paul Robey digs deep into the chart archives and plays through a 1950s countdown.",
        "alphanumericKey": "#",
        "image": {
            "type": "logo_unrestricted",
            "url": "https://mmo.aiircdn.com/cdn-cgi/image/width=1400,height=1400,fit=cover/460/66c3d3d69b2ac.jpg",
            "width": 1400,
            "height": 1400,
            "language": "en",
            "mimeValue": "image/jpeg",
            "index": 0
        },
        "genres": [
        {
            "href": "3.1.1",
            "name": "News",
            "type": "main"
        }
        ],
        "classicSeriesId": "'50svintagecharts"
    }
    ],
    "episodes": [
    {
        "uid": "2cfcf2876e9f229a353f65774c962101001831cf2e1bd14ec1777a829aa7cf13",
        "title": "'50s Vintage Charts",
        "podcastId": "16682",
        "expiryDate": "2125-01-26T15:05:00",
        "description": "Our chart supremo John Peters digs deep into his chart archives and plays through a 1950s countdown",
        "longDescriptions": [
        {
            "value": "Our chart supremo John Peters digs deep into his chart archives and plays through a 1950s countdown",
            "language": "en"
        }
        ],
        "onDemandStreams": [
        {
            "availableStart": "2025-01-26T15:05:00Z",
            "availableStop": "2125-01-26T15:05:00Z",
            "player": "https://www.boomradiouk.com/radioplayer/boom-light/od/items/50s-vintage-charts-26th-january/",
            "duration": 3900000,
            "audioStreams": [
            {
                "audioFormat": "",
                "streamSource": {
                    "url": "https://aod.sharp-stream.com/content/boom_light/storage/1737903974-50s_vintage_charts.mp3?aw_0_1st.ri=sharpstream&aw_0_1st.organization=sharpstream&awEpisodeId=cc03a13f-e8a6-4ba5-a227-0df63770b3bf&awCollectionId=boom_light-standalone&providerId=boom_light",
                    "mimeValue": "audio/mpeg"
                },
                "bitRate": {
                    "target": 128000,
                    "variable": false
                }
            }
            ]
        }
        ],
        "serviceName": "Boom Light from Boom Radio",
        "multimedia": [
        {
            "type": "logo_unrestricted",
            "url": "https://mmo.aiircdn.com/cdn-cgi/image/width=1400,height=1400,fit=cover/460/65c6723c740bb.jpg",
            "width": 1400,
            "height": 1400,
            "language": "en",
            "mimeValue": "image/jpeg",
            "index": 0
        }
        ],
        "alphanumericKey": "#",
        "mediumNames": [
        {
            "value": "'50s Vintage Cha",
            "language": "en"
        }
        ],
        "longNames": [
        {
            "value": "'50s Vintage Charts",
            "language": "en"
        }
        ],
        "links": [
        {
            "type": null,
            "url": "https://aod.sharp-stream.com/content/boom_light/storage/1737903974-50s_vintage_charts.mp3?aw_0_1st.ri=sharpstream&aw_0_1st.organization=sharpstream&awEpisodeId=cc03a13f-e8a6-4ba5-a227-0df63770b3bf&awCollectionId=boom_light-standalone&providerId=boom_light",
            "mimeValue": "audio/mpeg",
            "language": "en",
            "index": 0
        }
        ],
        "imageUrl": "https://mmo.aiircdn.com/cdn-cgi/image/width=1400,height=1400,fit=cover/460/65c6723c740bb.jpg",
        "consoleUrl": "https://www.boomradiouk.com/radioplayer/boom-light/",
        "url": "https://www.boomradiouk.com/radioplayer/boom-light/od/items/50s-vintage-charts-26th-january/",
        "startTime": "2025-01-26T15:05:00",
        "stopTime": "2125-01-26T15:05:00",
        "classicId": null
    }
    ]
}