simplesmartradio

Developer API

The SimpleSmartRadio public API returns the same data the site uses — search results, station detail, and a takedown endpoint. Free to use, no sign-up, no key.

The catalog data is open — built on open community sources and published back open.

Base URL

https://api.simplesmartradio.com

Rate limit

No formal limit currently enforced. We monitor server-side and will throttle on abuse. When throttling lands, over-limit responses will be HTTP 429 with body { error: "too many requests", code: "RATE_LIMITED" }.

CORS

Requests from simplesmartradio.com, *.simplesmartradio.pages.dev, and localhost:3000 are allowed by default. Other origins need no CORS headers because you can also call the API server-side.

Endpoints

GET /api/search

Returns a paginated list of stations matching the query. All filters are optional; at least one of q, genre, country, language must be present.

Query parameters:

  • q — text search across name, description, tags.
  • genre — hyphenated lowercase genre slug (e.g. jazz, classic-rock).
  • country — 2-letter ISO country code, lowercase (e.g. nl, gb).
  • language — 2-letter ISO language code, lowercase (e.g. en, de).
  • limit — page size, default 25, max 100.
  • offset — 0-based, default 0. The response includes next_offset when more results are available.

Example:

curl 'https://api.simplesmartradio.com/api/search?q=jazz&country=fr&limit=3'

GET /api/station/{slug}

Returns the full station detail plus up to six genre-related stations.

The slug is the URL fragment from a station page (<name>-<cc>-<id>, where id is a 32-character hex string).

curl 'https://api.simplesmartradio.com/api/station/bbc-world-service-gb-18185037436d63acb9a7678c6f4920d6'

POST /api/takedown

Submit a rights-holder takedown request. Body: { station_id, reason, contact }. Written to an R2 bucket for manual review. Responses: 202 Accepted on success.

GET /health

Returns { ok: true }. Use for uptime checks.

Data source

The catalog is built on open community data (radio-browser.info + Icecast YP) plus our own AI-driven enrichment. See the about page for the full data story.

Attribution

Not required for non-commercial use. Appreciated for anything public-facing — a link to simplesmartradio.com works.