Radioplayer

Developer Reference

 Back
Suggest Endpoint · Current

Radioplayer Developer Reference

Suggest Endpoint

Technical reference for Radioplayer partner integrations.

Version
Current
Document type
API reference
Audience
Radioplayer partner engineering teams

/{countryCode}/metadata/api/v2/suggest

Description

This endpoint provides search suggestions for live radio stations and on-demand episodes (podcasts). The suggestions are filtered based on the client's access permissions and the provided country code.

The API supports geo-based suggestions , meaning recommendations can be adjusted based on the user's location when latitude and longitude are provided.

The response includes:

Request Parameters

The request consists of query parameters (sent in the URL query string) and a header parameter.

Query ParametersName| Type| Required| Description

---|---|---|--- query| string| No| The user-provided search terms. If not specified, the API returns general keyword suggestions. lon| float| No| Longitude of the user location (used for geo-based suggestions). lat| float| No| Latitude of the user location (used for geo-based suggestions). geo| boolean| No| Enables or disables geo-based suggestions. Defaults to true. 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.

Example Request (Query Parameters)
GET /380/metadata/api/v2/suggest?query=rock&lat=45.4642&lon=9.1900&geo=true
Example Request with Header
GET /380/metadata/api/v2/suggest?query=rock
Content-Type: application/json
Radioplayer-Client: client@radioplayer.org

Response Format

The response provides search suggestions for radio stations and on-demand episodes. The keywords field contains terms that users might want to search for.

Sample Response for a request such as:
/826/metadata/api/v2/suggest/?query=b&geo=false

A truncated response containing some elements is shown below:

{
    "response":{
        "keywords":[
        {
            "name":"Platform B - Next Gen Radio Brighton "
        },
        {
            "name":"GB News Radio"
        },
        {
            "name":"Beyond Radio"
        }
        ],
        "live":[
        {
            "rpId":"461",
            "name":"Platform B - Next Gen Radio Brighton ",
            "description":"Launched in 2016, Platform B is Brighton & Hove’s only next gen radio station broadcasting on 105.5FM, DAB+ and online. Creatively led by next generation DJs, producers and presenters, this not-for-profit radio station is reimagining and diversifying the medium with an eclectic mix of music and youth programming broadcast from studios located in the heart of the city's New England cultural quarter. The radio station collaborates with 100+ young volunteers each year and is dedicated to providing relevant and engaging content created by & for 16-25 year olds who are underserved by mainstream broadcasters.",
            "groupName":"Community Media Association (CMA)",
            "multimedia":[
            {
                "width":600,
                "language":"en",
                "height":600,
                "mimeValue":"image/png",
                "index":2,
                "url":"https://assets.radioplayer.org/826/826461/600/600/lz9vxqub.png",
                "type":"logo_unrestricted"
            },
            {
                "width":288,
                "language":"en",
                "height":162,
                "mimeValue":"image/png",
                "index":8,
                "url":"https://assets.radioplayer.org/826/826461/288/162/lz9vxqud.png",
                "type":"logo_unrestricted"
            }
            ]
        }
        ],
        "onDemand":[
        {
            "odId":"e0ce91be999da1bd4f1923ef4e7368ffb64e436d65bb875c84651c6581cd3ed8",
            "rpId":"344",
            "name":"Jazzie B on James Brown",
            "description":"Soul II Soul’s Jazzie B tells Matthew Parris why he nominates James Brown, the “Godfather of Soul”, for this series.Jazzie B, who was awarded a CBE for services to black British music, spent time latterly with James Brown and he became “like a big brother.” He shares personal reflections on Mr Brown’s life and legacy, with help from the music journalist Charles Shaar Murray.Producer: Maggie AyreFirst broadcast on BBC Radio 4 in August 2014.",
            "series":{
                "id":"8229"
            },
            "player":"",
            "onDemandStreams":[
            {
                "audioStreams":[
                {
                    "bitRate":{
                        "target":0
                    },
                    "streamSource":{
                        "url":"http://open.live.bbc.co.uk/mediaselector/6/redir/version/2.0/mediaset/audio-nondrm-download-rss/proto/http/vpid/p02q541s.mp3",
                        "mimeValue":"audio/mpeg"
                    }
                }
                ]
            }
            ]
        }
        ]
    }
}

Notes