npm install radio-browser-api
This is a wrapper around free and open-source radio browser api. It simplifies the task of querying the API by creating methods for each API route and normalizing the responses and errors. It can be used both in the browser and in Node.js.
I suggest you familiarize yourself with the original API docs before using this library.
Also note that this library modifies the results from the API, because the API is brittle, in a way that returns duplicate stations, duplicated tags, or tags that are not tags rather, complete sentences. The library cleans this up for you.
API by default, returns broken
stations (stations that are in the system but don't have their streams up and running) library by default hides those stations ( this can be changed when creating the library instance, or per API call)
First, you need to instantiate the class instance and pass in an object that represents the fetch
. So when using this module on the server side, make sure you have a fetch implementation (e.g node-fetch) available. You should also have an application name this is going to be passed as user agent string
when talking to the API. You can use whatever you like but be consistent.
Server:
import nodeFetch from 'node-fetch'
import { RadioBrowserApi } from 'radio-browser-api'
const api = new RadioBrowserApi(
(nodeFetch as unknown) as typeof fetch,
'My Radio App'
)
Browser:
import { RadioBrowserApi } from 'radio-browser-api'
const api = new RadioBrowserApi(fetch.bind(window), 'My Radio App')
After you instantiate the class, you can get the list of available API servers (I know, weird right?). Essentially the underlying API URLs can change and the author has two to three servers always running. Something like:
https://fr1.api.radio-browser.info
or https://de1.api.radio-browser.info
This step is not mandatory because the class has one of the servers hardcoded, but If you get errors that service is not available, you can query for available servers.
const api = new RadioBrowserApi(fetch.bind(window), 'My Radio App')
api.resolveBaseUrl().then((urls: { ip: string; name: string }[]) => {
// set the server to be used for all api calls
api.setBaseUrl(urls[o0].ip)
})
There are a lot of methods you can use to query the API.
import { RadioBrowserApi } from 'radio-browser-api'
//browser
const api = new RadioBrowserApi(fetch.bind(window),'My Radio App')
// query stations by country code and limit to first 100 stations
const stations = await api.searchStations({
countryCode: 'US',
limit: 100,
offset: 0 // this is the default - can be omited
})
// get next 100 stations
const stations = await api.searchStations({
countryCode: 'US',
limit: 100,
offset: 1 // 1 - is the second page
})
// query stations by languge and tag
const stations = await api.searchStations({
language: 'english',
tag:'jazz'
limit: 100
})
// query stations by array of tags
const stations = await api.searchStations({
tagList: ['dance','house']
})
//etc..
The response that you get from searching the stations is an array of station objects. The structure of the station object looks like this.
type Station = {
changeId: string // A globally unique identifier for the change of the station information
id: string // A globally unique identifier for the station
name: string // The name of the station
url: string // The stream URL provided by the user
urlResolved: string // An automatically "resolved" stream URL.
homepage: string // URL to the homepage of the stream.
favicon: string // URL to an icon or picture that represents the stream. (PNG, JPG)
tags: string[] // Tags of the stream
country: string // Full name of the country
countryCode: string // Official countrycodes as in ISO 3166-1 alpha-2
state: string // Full name of the entity where the station is located inside the country
language: string[] // Languages that are spoken in this stream.
votes: number // Number of votes for this station
lastChangeTime: Date // Last time when the stream information was changed in the database
codec: string // The codec of this stream recorded at the last check.
bitrate: number // The bitrate of this stream recorded at the last check.
hls: boolean // Mark if this stream is using HLS distribution or non-HLS.
lastCheckOk: boolean // The current online/offline state of this stream.
lastCheckTime: Date // The last time when any radio-browser server checked the online state of this stream
lastCheckOkTime: Date // The last time when the stream was checked for the online status with a positive result
lastLocalCheckTime: Date // The last time when this server checked the online state and the metadata of this stream
clickTimestamp: Date // The time of the last click recorded for this stream
clickCount: number // Clicks within the last 24 hours
clickTrend: number // The difference of the clickcounts within the last 2 days. Positive values mean an increase, negative a decrease of clicks.
}
When you try to play the stream you should use urlResolved
property of the station object. API documentation says this about the property:
An automatically "resolved" stream URL. Things resolved are playlists (M3U/PLS/ASX...), HTTP redirects (Code 301/302). This link is especially useful if you use this API from a platform that is not able to do resolve on its own (e.g. JavaScript in browser) or you just don't want to invest the time in decoding playlists yourself.
Some API routes are not covered, mainly because it would add to the size of the package, and the routes that are not covered are used for API diagnostic purposes and are not of much value to the end-user. However, pull requests are always welcomed 👍.