# Open Radio Player API for agents

Use this public, read-only JSON API to find a station, identify its scheduled show, and give someone a link to listen. Send HTTPS GET requests to `https://openradioplayer.com`. No key, account, or cookies are required.

## Find a station and give the listener a link

```sh
curl -fsS 'https://openradioplayer.com/api/v1/stations/index.json'
```

In `items[]`, search `stationName`, `city`, `stationId`, or `aliases[]`. Keep the canonical `stationId` for programming requests. Give the listener the station’s `listenUrl`, such as [WBGO’s player](https://openradioplayer.com/wbgo/lander). With an older catalog, use `https://openradioplayer.com/{defaultStreamId}/lander`. For an audio client, return the catalog’s current `stream.url`. Choose an alternate from `streams[]` if its `transport` or playback compatibility fits the client better. A stream URL can change.

## What is on this station?

```sh
curl -fsS 'https://openradioplayer.com/api/v1/stations/wpkn/now-next'
curl -fsS 'https://openradioplayer.com/api/v1/stations/wpkn/schedule?days=7'
```

Now/Next returns `current` and `next`. Schedule returns `occurrences[]`. Add `from=YYYY-MM-DD` for a specific date in the station’s time zone and choose `days` from 1 through 14. Use `startAt` and `endAt` to display times in the listener’s time zone. Each end is exclusive. Credit the station and link its `source.url`.

For example, this historical Now/Next excerpt shows a one-off WPKN listing at 4 pm in Bridgeport on November 14, 2026:

```json
{
  "stationId": "wpkn",
  "availability": "available",
  "asOf": "2026-11-14T21:00:00.000Z",
  "current": {
    "title": "Springsteen Saturday, On-Air Fundraiser",
    "startAt": "2026-11-14T20:00:00.000Z",
    "endAt": "2026-11-14T23:00:00.000Z"
  }
}
```

At that instant a listener could hear the scheduled fundraiser until 6 pm Eastern. Use a new request for a question about today.

## Who is airing Latin jazz right now?

```sh
curl -fsS 'https://openradioplayer.com/api/v1/stations/programming?ids=wbgo,wpkn,kxlu&days=2'
```

Read each item's `nowNext.current` for a present-tense answer, or search `schedule.occurrences[]` for a future airing. Match the actual listed show to the request. A station’s jazz genre alone establishes only its general format. If a show title is ambiguous, report it as a possible lead and use the station’s source to verify its musical style before calling it Latin jazz. The three stations above are a starting selection. For a catalog-wide question, take the IDs from the catalog and request groups of up to 50. Report the scope you checked and any missing listings. The batch accepts 1–7 days and either comma-separated `ids` or an exact catalog `genre` with at most 50 stations.

## What if the listing is missing?

```sh
curl -fsS 'https://openradioplayer.com/api/v1/stations/wcpe/now-next'
```

Check the requested station’s `availability`, `reason`, `validFrom`, `validThrough`, and `staleAt` before naming a show. For a current show, require an available, unexpired response and `startAt <= now < endAt`. Use `sourceObservedAt` to describe when the source was checked. Return the available station link even if the guide has a gap. For example, with `current: null`, say “I don’t have a confirmed current listing for WCPE. [Listen to WCPE](https://openradioplayer.com/wcpe/lander).”

Known stations with stale, unavailable or unsupported programming return HTTP 200. Unknown IDs return 404. Invalid dates or oversized batches return 400. Use only the dated occurrences returned. A verified recurring lineup can remain available with `scheduleBasis.reviewStatus: "overdue"`. Disclose the last check when using it. An exact-URL ETag can save a repeat transfer. A 304 reuses the cached representation and its original source dates.

## Track and stream information

For the exact song or classical work, request `/api/v1/stations/{stationId}/now-playing` and check its own availability. Live track data requires a source-specific rights record. If the response is unsupported, tell the listener the track is unknown. Schedule titles identify programs.

[Healthy streams](https://openradioplayer.com/api/v1/stations/healthy) and [telemetry](https://openradioplayer.com/api/v1/stations/telemetry) report observed reliability. Match the telemetry’s `streamId` to a catalog stream’s `id`. [System status](https://openradioplayer.com/api/v1/system/status) reports the monitoring pipeline’s health. Listener playback can vary by device and network.

The [OpenAPI schema](https://openradioplayer.com/openapi.json) describes all endpoints, query limits and response fields.
