canonical: https://jentic.com/apis/npr.org/npr-station-finder-service

# NPR Station Finder Service

The NPR Station Finder Service lets clients look up NPR member station information by location, frequency, or station ID. It returns details about each station's broadcast streams, programming schedules, member affiliations, and donation URLs. Built for NPR One and partner applications, the service exposes two endpoints under `/v3/stations` and is a thin wrapper around NPR's authoritative member station registry.

## For AI agents

Look up NPR member station metadata by geography or station ID, including stream URLs and donation pages. Two endpoints under `/v3/stations` covering search and detail retrieval.

## Scope

Does not handle audio playback, podcast search, or sponsorship insertion - use for NPR member station metadata lookup only.

## Capabilities

- Search NPR member stations by latitude, longitude, ZIP code, city, or state
- Retrieve a specific station's full profile via its unique station ID
- Surface live audio stream URLs for each member station's HD and standard broadcasts
- Expose station donation and pledge URLs for in-app member support flows
- Return programming schedule and call sign data for downstream NPR One clients

## Use cases

### Geo-located Station Lookup for Voice Apps

Voice assistants and smart-speaker skills use the Station Finder to resolve a listener's location into a specific NPR member station, returning its primary live stream URL so the assistant can begin playback. The `/v3/stations` endpoint accepts latitude and longitude pairs and returns ranked matches with stream metadata, removing the need for clients to maintain their own station database.

Example prompt: Call GET `/v3/stations` with lat=40.7128&lon=-74.0060 and extract the streamUrl for the top-ranked WNYC result

### Member Pledge and Donation Routing

Member-supported audio apps surface donation links scoped to each listener's home station. The Station Finder returns a donationUrl per station, letting product teams route pledge clicks to the correct local affiliate without hardcoded mappings. This is critical during pledge drives when traffic must reach the right station's fundraising portal.

Example prompt: Resolve station ID 305 via GET `/v3/stations/{stationId}` and return the donationUrl for the in-app pledge button

### AI Agent Audio Discovery via Jentic

AI agents that recommend or play public radio content use Jentic to discover the Station Finder, search for stations matching a user's intent, and execute the lookup with isolated credentials. Through Jentic, an agent can resolve a phrase like "play my local NPR station" into a concrete `/v3/stations` call without browsing NPR developer docs.

Example prompt: Use Jentic to search for 'find local NPR station' and execute the resulting `/v3/stations` operation with the user's lat/lon

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v3/stations` | Search NPR member stations by location or other criteria |
| GET | `/v3/stations/{stationId}` | Retrieve a single station's full profile by ID |

## Key resources

- **Stations** — Search and retrieve NPR member station metadata, stream URLs, and donation links

## Why Jentic

- **Setup:** Wiring the NPR Station Finder Service by hand means carrying an OAuth 2.0 token into calls to station.api.npr.org and mapping the station lookup operations yourself. Through Jentic you install once, import the NPR Station Finder Service from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** This service puts the station id in the URL path (`/v3/stations/{stationId}`), so a rule can pin your agent to one station and nothing else. Both operations here are read-only lookups, so you choose whether the agent lists stations, reads a single station, or both.
- **Credential handling:** Your NPR OAuth client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a local NPR station by ZIP', and Jentic returns the matching `/v3/stations` operation with its query schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NPR Station Finder** — Duplicate v3 station finder spec hosted under a shorter slug
- **NPR Sponsorship Service** — Returns sponsorship messages to play alongside NPR audio streams
- **Listen Notes** — Podcast and audio search across many publishers, not just NPR

## FAQ

### What authentication does the NPR Station Finder Service use?

The NPR Station Finder Service uses OAuth 2.0 authorization code flow against https://authorization.api.npr.org/v2/token. Tokens are scoped to identity.readonly, listening.readonly, and related NPR One scopes. Through Jentic, these client credentials are stored encrypted in the vault and never appear in agent prompt context.

### Can I search for NPR stations by latitude and longitude with the NPR Station Finder Service?

Yes. GET `/v3/stations` accepts geographic query parameters and returns ranked station matches with their stream URLs, call signs, and donation pages.

### What are the rate limits for the NPR Station Finder Service?

NPR's developer portal at https://dev.npr.org does not publish a fixed rate limit on this service, but partner applications are expected to cache station results because the underlying data changes infrequently.

### How do I look up a single NPR station through Jentic?

Search Jentic for 'NPR station details by ID', load the GET `/v3/stations/{stationId}` schema, and execute with the numeric station ID. The flow is: pip install jentic, then await client.search, load, and execute.

### Is the NPR Station Finder Service free to use?

Access requires registering an OAuth client at https://dev.npr.org. NPR does not charge for the API itself but restricts use to apps that comply with their NPR One Enterprise terms.

### Can I limit what my agent is allowed to do with the NPR Station Finder Service?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and both operations here are read-only lookups, so you choose whether the agent can list stations with GET `/v3/stations`, read one station with GET `/v3/stations/{stationId}`, or both. Since the station ID sits in the URL path, you can pin the agent to a single station and block everything else. Your NPR OAuth client credentials stay with your own instance and are injected only at execution time, never entering the agent's prompt or context.