API Reference

http

    Supplies a list of category names and their hrefs

    /categories

    Returns a list of categories and hrefs for either live or on-demand content.

    Please note: there is a lack of uniformity amongst category names that impacts the effectiveness of this endpoint. As such a developer may need to keep lookup tables to match like categories across countries. Note that categories change very seldom. Radioplayer uses the term 'categories' interchangably with the term 'genres' to refer to Radioplayer's single taxonomy system for radio content.

    Results are returned on a per country basis through use of the mandatory country parameter, and can only be for live or on-demand content, not both. The category hrefs can then be used with the /v2/ondemand and /v2/stations endpoints to return results filtered by that category.

    Endpoint

    Base URL: https://api.radioplayer.org/v2/categories

    Request Parameters

    Header Fields

    To find out how to correctly construct authentication headers for the Radioplayer Partner API (WRAPI) please see the Authentication guide.

    Query Parameters

    Live look up by country

    /v2/categories/?country=372&type=live

    On demand lookup by country

    /v2/categories/?country=372&type=ondemand
    QUERY PARAMETER VALUE
    country Required. An ISO 3166 numeric country code. When applied only returns results from the specified country.
    type Required. This parameter controls whether the categories returned describe live or ondemand data.

    Response

    Sample header response

    content-type: application/json; charset=utf-8
x-ratelimit-limit: 300000
x-ratelimit-remaining: 285030
x-ratelimit-reset: 1585699200

    When successful, the HTTP status code in the response header is 200 OK. One or more category names and their hrefs are returned in a list in JSON format (or on special request, XML supported by the RadioDNS schema).

    If there is an error, the header returns an error status code.

    The WRAPI also includes information about your monthly request quota in the returned header.

    This includes information on:

    • Your total monthly quota
    • How many requests you have remaining for the month
    • When the quota will be reset, given as a UNIX timestamp.

    Example Response Body

    {
  "data": [
    {
      "href": "urn:radioplayer:metadata:cs:Category:2012:5",
      "name": "Classical and World"
    },
    {
      "href": "urn:radioplayer:metadata:cs:Category:2012:7",
      "name": "Comedy, Drama and Kids"
    },
    {
      "href": "urn:radioplayer:metadata:cs:Category:2012:3",
      "name": "Dance and RnB"
    },
    {
      "href": "urn:radioplayer:metadata:cs:Category:2012:4",
      "name": "Easy, Oldies and Jazz"
    },
    {
      "href": "urn:radioplayer:metadata:cs:Category:2012:6",
      "name": "News, Sport and Talk"
    },
    {
      "href": "urn:radioplayer:metadata:cs:Category:2012:1",
      "name": "Pop and Chart"
    },
    {
      "href": "urn:radioplayer:metadata:cs:Category:2012:2",
      "name": "Rock and Indie"
    }
  ],
  "meta": {
    "nesting": false,
    "paginated": false,
    "dataType": "categories",
    "count": 7,
    "fromCache": false,
    "cacheExpiresAt": null
  }
}

    The returned response body consists of a meta and data object.

    The possible meta field values for this endpoint are:

    FIELD VALUE
    paginated Optional, Boolean. Sets how or if results are grouped into pages.

    For more information on pagination, see the API Documentation index.
    nesting Optional, Boolean. Indicates whether full data objects are nested within other objects.

    In this endpoint this value is always set to false.

    For more information on nesting, see the API Documentation index.
    dataType Object type returned by the request. In this case it is categories.
    count Optional, string. A number describing how many items are in the data set.
    fromCache Optional, Boolean. Indicates whether this data came from cached data.

    For more information on caching, please see the API Documentation index.
    cacheExpiresAt Optional. UNIX timestamp indicating when the cache will expire.

    For more information on caching, please see the API Documentation index.

    The expected data field values for this endpoint are:

    FIELD VALUE
    href A URN which uniquely identifies a category. Uniqueness applies on a per-country basis not pan-country.
    name A text string in local language describing the category. This may be used directly in interfaces
    http