{"id":20252426,"url":"https://github.com/ivandotv/radio-browser-api","last_synced_at":"2025-04-05T05:04:02.746Z","repository":{"id":37985412,"uuid":"282991823","full_name":"ivandotv/radio-browser-api","owner":"ivandotv","description":"Wrapper around free and open-source radio browser API. It simplifies the task of querying the API","archived":false,"fork":false,"pushed_at":"2024-12-23T18:49:54.000Z","size":2213,"stargazers_count":62,"open_issues_count":3,"forks_count":17,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T04:07:00.706Z","etag":null,"topics":["api","radiobrowser-api"],"latest_commit_sha":null,"homepage":"https://api.radio-browser.info/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivandotv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-27T19:10:34.000Z","updated_at":"2025-03-02T13:32:42.000Z","dependencies_parsed_at":"2024-06-18T22:50:41.043Z","dependency_job_id":"7bd3899d-893e-432f-b95c-c08d2b1eef59","html_url":"https://github.com/ivandotv/radio-browser-api","commit_stats":{"total_commits":137,"total_committers":9,"mean_commits":"15.222222222222221","dds":"0.46715328467153283","last_synced_commit":"085797b5ce255ab152061bc033be4c0d02752d3f"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivandotv%2Fradio-browser-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivandotv%2Fradio-browser-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivandotv%2Fradio-browser-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivandotv%2Fradio-browser-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivandotv","download_url":"https://codeload.github.com/ivandotv/radio-browser-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289424,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","radiobrowser-api"],"created_at":"2024-11-14T10:16:40.509Z","updated_at":"2025-04-05T05:04:02.731Z","avatar_url":"https://github.com/ivandotv.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Radio Browser API\n\n[![Test](https://github.com/ivandotv/radio-browser-api/actions/workflows/CI.yml/badge.svg)](https://github.com/ivandotv/radio-browser-api/actions/workflows/CI.yml)\n[![Codecov](https://img.shields.io/codecov/c/github/ivandotv/radio-browser-api)](https://app.codecov.io/gh/ivandotv/radio-browser-api)\n[![GitHub license](https://img.shields.io/github/license/ivandotv/tinga)](https://github.com/ivandotv/radio-browser-api/blob/main/LICENSE)\n[![semantic release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\n## Install\n\n```js\nnpm install radio-browser-api\n```\n\n## Table of Contents\n\n- [What is it](#what-is-it)\n- [Usage](#usage)\n- [Package level API Docs](docs/api/README.md)\n\n## What is it\n\nThis is a wrapper around free and open-source [radio browser api](https://api.radio-browser.info/).\nIt 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**.\n\nI suggest you familiarize yourself with the [original API docs](https://de1.api.radio-browser.info/) before using this library.\n\nAlso 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 but rather, complete sentences. The library will clean this up for you.\n\nAPI 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)\n\nFor an example of usage of this library check [live radio repository](https://github.com/ivandotv/live-radio)\n\n## Usage\n\nIf using in node.js environment, make sure you have a fetch implementation (e.g [node-fetch](https://www.npmjs.com/package/node-fetch)) available. You should also have an application name that is going to be passed as `user agent string` when talking to the API. You can use whatever you like but be consistent, the author of the API uses it to track usage statistics.\n\n```ts\nimport { RadioBrowserApi, StationSearchType } from 'radio-browser-api'\n\nconst api = new RadioBrowserApi('My Radio App')\n\nawait api.getStationsBy(StationSearchType.byTag, 'jazz')\n```\n\n### Querying the API\n\nThere are a lot of methods you can use to query the API.\n\n```ts\nimport { RadioBrowserApi } from 'radio-browser-api'\n\nconst api = new RadioBrowserApi('My Radio App')\n\n// query stations by country code and limit to first 100 stations\nconst stations = await api.searchStations({\n  countryCode: 'US',\n  limit: 100,\n  offset: 0 // this is the default - can be omited\n})\n// get next 100 stations\nconst stations = await api.searchStations({\n  countryCode: 'US',\n  limit: 100,\n  offset: 1 // 1 - is the second page\n})\n\n// query stations by languge and tag\nconst stations = await api.searchStations({\n  language: 'english',\n  tag:'jazz'\n  limit: 100\n})\n\n// query stations by array of tags\nconst stations = await api.searchStations({\n  tagList: ['dance','house']\n})\n\n// query stations with or without geolocation info\nconst stations = await api.searchStations({\n  hasGeoInfo: true // not set=display all, true=show only stations with geo_info, false=show only stations without geo_info\n})\n\n//etc..\n```\n\nThe response that you get from searching the stations is an array of station objects. The structure of the station object looks like this.\n\n```ts\ntype Station = {\n  changeId: string // A globally unique identifier for the change of the station information\n  id: string // A globally unique identifier for the station\n  name: string // The name of the station\n  url: string // The stream URL provided by the user\n  urlResolved: string // An automatically \"resolved\" stream URL.\n  homepage: string // URL to the homepage of the stream.\n  favicon: string // URL to an icon or picture that represents the stream. (PNG, JPG)\n  tags: string[] // Tags of the stream\n  country: string // Full name of the country\n  countryCode: string // Official countrycodes as in ISO 3166-1 alpha-2\n  state: string // Full name of the entity where the station is located inside the country\n  language: string[] // Languages that are spoken in this stream.\n  votes: number // Number of votes for this station\n  lastChangeTime: Date // Last time when the stream information was changed in the database\n  codec: string // The codec of this stream recorded at the last check.\n  bitrate: number // The bitrate of this stream was recorded at the last check.\n  hls: boolean // Mark if this stream is using HLS distribution or non-HLS.\n  lastCheckOk: boolean // The current online/offline state of this stream.\n  lastCheckTime: Date // The last time when any radio-browser server checked the online state of this stream\n  lastCheckOkTime: Date // The last time when the stream was checked for the online status with a positive result\n  lastLocalCheckTime: Date // The last time when this server checked the online state and the metadata of this stream\n  clickTimestamp: Date // The time of the last click recorded for this stream\n  clickCount: number // Clicks within the last 24 hours\n  clickTrend: number // The difference of the clickcounts within the last 2 days. Positive values mean an increase, negative a decrease of clicks.\n  geoLat: number | null // Latitude on earth where the stream is located. Null if it doesn't exist.\n  geoLong: number | null // Longitude on earth where the stream is located. Null if it doesn't exist.\n}\n```\n\n#### Important\n\nWhen you try to play the stream you should use `urlResolved` property of the station object. API documentation says this about the property:\n\n\u003e 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.\n\nSome 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 👍.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivandotv%2Fradio-browser-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivandotv%2Fradio-browser-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivandotv%2Fradio-browser-api/lists"}