AirwaveDB API

Generated public API and distribution layer for the AirwaveDB internet radio directory.

AirwaveDB indexes internet radio stations and their playable stream endpoints. This repository is built from AirwaveDB/database and AirwaveDB/streams; generated files should not be edited manually.

database (station metadata) ─┐
                             ├─> api (generated public view)
streams  (playable URLs)  ───┘

database and streams are the canonical sources. api is a generated consumer-facing view of both datasets.

Endpoints

Route	Description
GET /v1	Dataset counts, source snapshots, and build timestamps
GET /v1/stations	All station metadata
GET /v1/stations/:id	One station with its streams
GET /v1/streams	All playable stream records
GET /v1/countries	Country index
GET /v1/countries/:code	Stations and streams for one country
GET /v1/categories	Category index
GET /v1/categories/:id	Stations and streams for one category
GET /v1/languages	Canonical language index
GET /v1/languages/:code	Stations and streams for one canonical code or accepted alias
GET /v1/language-aliases	Accepted language aliases and their canonical codes

Country codes use lowercase ISO 3166-1 alpha-2 values in URLs. Language records use the canonical codes stored by AirwaveDB.

Examples:

GET /v1/countries/jp
GET /v1/categories/news
GET /v1/languages/ja
GET /v1/languages/jpn
GET /v1/stations/awb_0123456789abcdef0123

Language aliases

Equivalent ISO 639 forms remain usable for backwards compatibility. For example, jpn resolves to the same station set as ja, eng resolves to en, and both deu and ger resolve to de.

Canonical language responses look like:

{
  "code": "ja",
  "stationCount": 117,
  "stations": []
}

Alias responses preserve the requested code and expose the canonical target:

{
  "code": "jpn",
  "canonicalCode": "ja",
  "stationCount": 117,
  "stations": []
}

GET /v1/languages contains canonical entries only. GET /v1/language-aliases exposes the compatibility map separately.

Static distributions

The generated JSON files can also be consumed without the HTTP router:

https://raw.githubusercontent.com/AirwaveDB/api/main/v1/index.json
https://raw.githubusercontent.com/AirwaveDB/api/main/v1/stations.json
https://raw.githubusercontent.com/AirwaveDB/api/main/v1/streams.json
https://raw.githubusercontent.com/AirwaveDB/api/main/v1/countries/jp.json
https://raw.githubusercontent.com/AirwaveDB/api/main/v1/categories/news.json
https://raw.githubusercontent.com/AirwaveDB/api/main/v1/languages/ja.json
https://raw.githubusercontent.com/AirwaveDB/api/main/v1/languages/jpn.json
https://raw.githubusercontent.com/AirwaveDB/api/main/v1/language_aliases.json

Bulk NDJSON distributions are available at:

/v1/stations.ndjson
/v1/streams.ndjson

The public distribution formats currently generated by this repository are JSON and NDJSON.

Station lookup

Station IDs are stable AirwaveDB identifiers. The routed API resolves a station ID to a single JSON object without requiring clients to download the full station dataset.

The generated lookup shards under v1/_lookup/ are implementation details and are not part of the public API contract.

Data model

A station is a radio service. A stream is one playable endpoint belonging to that station.

Station identity and metadata are maintained in AirwaveDB/database. Stream endpoints are maintained in AirwaveDB/streams. Consumer-facing country, category, language, and station responses join both datasets.

Reproducible snapshots

Each API build resolves the current database and streams branches to immutable Git commit SHAs before reading any source files. Every file in a build therefore comes from one fixed commit in each canonical repository rather than a moving main URL.

v1/index.json records those commits under sourceSnapshots, together with the canonical generation timestamps, schema versions, and the stream identity strategy. The build is rejected if the selected streams snapshot was generated from a different database snapshot. This also avoids transient raw.githubusercontent.com/main cache skew after canonical data updates.

Deployment

wrangler.toml deploys v1/ as static assets and src/worker.js provides the extensionless HTTP routes listed above.

npx wrangler deploy

Updates

Generated files are rebuilt automatically from the current database and streams repositories. Generated files should not be edited manually.

License

AirwaveDB's generated directory data is released under CC0 1.0. Third-party station names, logos, websites, stream endpoints, and broadcasts remain subject to their respective owners' rights.