How to optimise API usage – keeping your applications efficient

Introduction

Radioplayer offers access to the best possible metadata, covering radio stations, schedules, and broadcast on-demand content, sourced directly from the broadcasters themselves. No other service can provide such extensive and rich breadth of content.

When you first open your account with Radioplayer, a monthly quota is set after your trial. This is based on your projected usage, and becomes available after the payment of an initial set-up fee. This quota is then refreshed at the beginning of each calendar month.

Radioplayer helps you manage this monthly quota by issuing you with email advisories whenever you have used over 80% of your quota

Quota Management Reminders

Radioplayer notifies you with emails to let you know when you have used up over 80% of your quota of requests, so you can plan how to use your resources appropriately.

You will also receive an additional email when your quota is used up. Requests made to our service once your quota is exhausted are returned with a 429 error code.

If you receive this code within your responses and require more data access, please contact your account manager at Radioplayer.

Server-side usage monitoring

Radioplayer supplies server-side functionality to improve the performance of our APIs.

Most Radioplayer responses are structured this way:

{
  "meta": {
      "paginated": false,
      "count": 270
  },
  "data": [
      { OBJECT },

      ...
}

You can see here in this example response that the envelope contains two objects – meta and data:

• The data array contains the data that is returned by a successful request to the Radioplayer metadata service.
• The meta object controls the amount of results returned and whether that data is paginated or not.

In this way you can not only control how much data is returned per request, but also how that data is relayed to the user.

Setting selective caching information

Intelligent use of server-side caching improves the performance of the Radioplayer Partner API (WRAPI) and also allows for more economical use of your monthly data quota.

You can make a request and then manage what is returned through use of the following keys:

• fromCache – this flag indicates whether the data has come from the cache or not
• cacheExpiresAt – this field gives an expiry time for the data, in UNIX universal time. It is expected that your middleware will retain the response until at least this time.

These fields are used in the meta object and feature as part of the response:

{
  "meta": {
    "nesting": false,
    "paginated": false,
    "dataType": "stations",
    "count": 1,
    "fromCache": true,
    "cacheExpiresAt": 1584990057378
  }
}

Different kinds of data can be set to have different caching values. So, for instance, the basic identification details of a radio station – its name, its location, etc, are not likely to change that much. It is therefore probably not necessary to refresh that data with every request – daily would be sufficient. Others might require caching more often.

Here are some recommended guidelines for caching data:

Filtering using query parameters

Whilst there are no policy limits on how much data you accept ‘over the wire’ from Radioplayer at any one time, you might wish to control the size of the response payloads to optimise the performance of your apps. You can control the amount of data returned within your requests through the use of parameters.

Unless you apply query parameters, everything that could possibly apply to your request in the Radioplayer metadata service will be returned to you – bearer IDs, social media information, branding copy, etc.

Depending on what you are working with you may not need all this, so you can cut down on your network load through the selective use of query parameters.

Which parameters apply to which query differs depending on the WRAPI endpoint being used, so for a more advanced discussion of the use of query strings within the Radioplayer Partner API (WRAPI), please see the API documentation.

Keeping a watch on your current usage

To help you track your request usage, we return custom HTTP headers with every response. These include the following information:

x-ratelimit-limit: 30000
x-ratelimit-remaining: 28663
x-ratelimit-reset: 1585699200

These headers indicate:

• The overall size of your quota
• How many requests you have remaining this month
• The date, shown as a UNIX timestamp, when your allowances reset.

If you notice that your allowances are running out sooner than expected, you can employ more aggressive caching strategies – or discuss with your Radioplayer account manager about enlarging your current quota size with Radioplayer.