API.radio-browser.info docs

Infos

This API (Release Notes) is completely free and open source. Your freedoms are:
  • You may use it in free and non free software.
  • You may install it on your own server and mirror all its data.
  • You may fork it
  • You may look at the stats
  • You may look at the network structure

HowTo

There are 2 possible ways to use this API:
  • use it directly
  • use 3rd party libraries

use it directly

These steps should be done in your APP or program.
  1. Get a list of available servers

    Do a DNS-lookup of 'all.api.radio-browser.info'. This gives you a list of all available servers. To get the nice names you can do a reverse DNS-Lookup of the entries from the first request and display them to the user. There are some examples of how to do this in different languages: NodeJS (prefered), NodeJS, Python 2, Python 3, Java (Android), C#, Javascript(Browser)
    Now you have a list of multiple names of servers which you can use to directly connect to with HTTP and preferably HTTPS.
    Example: https://de1.api.radio-browser.info, https://de2.api.radio-browser.info, ..

    (Alternative: query the DNS SRV record of _api._tcp.radio-browser.info which gives you the list of server names directly without reverse dns lookups.)

  2. Randomize the list

    Either let the user choose one server from the list with a dialog or
    just randomize the list and choose the first entry of the now random list. If a request fails just retry the request with the next entry in the list.

  3. Remember the following things
    • Send a speaking http agent string (e.g. mycoolapp/1.4)
    • Send /json/url requests for every click the user makes, this helps to mark stations as popular and makes the database more usefull to other people.
    • Send feature requests/bugs to GitLab
  4. Continue with the docs of the server

    I try to keep them all at the same version, so they should always all be the same.
    Here are some examples of working servers:
    https://de1.api.radio-browser.info, https://nl.api.radio-browser.info, https://at1.api.radio-browser.info
    Click the links to find out about the API. Please remember that any of them may go down in the future, which means that you always should follow the previous steps in your app.

3rd party libraries

Notice

Users of the old API (SERVER = www.radio-browser.info) should migrate to the new one. It uses a newer server software, which is actively maintained and which is faster.

I am still using the old API, what should I do?

There are only a few minor changes in the api. Most things can be kept the same.
  1. Do NOT use the "id" fields anymore! They do not work accross multiple servers. Use the uuid fields instead (e.g.: stationuuid, checkuuid, clickuuid). These fields are kept consistend accross servers in the network. If you still use id fields to for example keep a favourite station list please change this behaviour as soon as posible.
  2. Do NOT use the "country" fields anymore! Use "countrycode" instead, which is standardized.
  3. In the JSON some fields that were previously strings, are now numbers or bools. Please visit the docs for that.
  4. Never use a direct link to a single new server. It is much better to get a list of the servers like described above. Available server names may change.