This API (Release Notes
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
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.
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, Python,
Now you have a list of multiple names of servers which you can use to directly connect to
HTTP and preferably HTTPS.
Example: https://de1.api.radio-browser.info, https://de2.api.radio-browser.info, ..
Choose an entry from the list
Either let the user choose one server from the list with a dialog or
just choose a random one. It is a good idea to check the choosen one with a simple status
request to "/stats" if it still works.
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 github
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:
Click the links to find out about the API. Please remember that any of them may go down in
which means that you always should follow the previous steps in your app.
3rd party libraries
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.
- Do NOT use the "id" fields anymore! They do not work accross multiple servers. Use the uuid
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.
Do NOT use the "country" fields anymore! Use "countrycode" instead, which is standardized.
In the JSON some fields that were previously strings, are now numbers or bools. Please visit
the docs for that.
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.