| NPR Shop | NPR Social Media | Sign In | Register

Get started!
Login
| Register

 

Station Finder API

The Station Finder API can be used to identify local NPR member stations based on zip code, city/state, unique ID, call letters, longitude/latitude, and a few other parameters. This is the same data that powers the Station Finder. This tool only returns NPR member stations or stations that carry NPR programming.

Station Finder API Reference
 

As further described below, the Station Finder API is RESTful, although the API key is passed in as a query string parameter with all requests. To get a key, you must register. You also must obtain permission to use the Station Finder API from NPR. Your API key is visible on the Your Account page.

The Station Finder API provides two endpoints:

Search by Organization ID
Method: GET
Endpoint: http://api.npr.org/v2/stations/org/${org_id}
Searches for a station by its assigned organization ID. If you are not sure of the stations's organization ID, it is included in the search results when using the Search by Query endpoint.

Search by Query
Method: GET
Endpoint: http://api.npr.org/v2/stations/search/${search_query}
The search query searches all data elements and returns all matching stations with full or partially matching: name, network name, call letters, tagline, band, and address. You may also conduct one of the following geographic searches, which return all stations that can be heard at that location:

  • City / State Passed in as city,st
  • Latitude / Longitude Passed in as lat,long

One item included with each station record returned by the API is a collection of URLs that point to various pages (e.g. the home page), graphics such as logos, social media pages, and audio streams including podcasts and station identifiers. If you are migrating an application from an older version of the API you will need to change your application to pull these URL's from the collection instead of using a top level element. A few URLs may still be obtained using top level elements but these are deprecated and will be removed in a future release.

 
Station Finder API Examples
 

The following are examples of how to call the Station Finder API:

Search by call letters
http://api.npr.org/v2/stations/WAMU?apiKey=demo

Search by zip code
http://api.npr.org/v2/stations/20902?apiKey=demo

Search by city/state
http://api.npr.org/v2/stations/Silver+Spring,MD?apiKey=demo

Search by latitude/longitude
http://api.npr.org/v2/stations/37.22987,80.41769?apiKey=demo

Search by organization ID
http://api.npr.org/v2/stations/org/202?apiKey=demo

 
Station Finder Output Example
 


 
Station Finder Output Definitions
 

Below is a description for each of the most important elements returned for each station in the result set.

org_id
This element is always returned in the output and is the system's unique id for that station. This element is the same as the orgId used in the Story API, representing the owner of the story.

call / band
call, and band are always returned with each station result. This combination is the unique identifier for the station. (e.g. WAMU-FM).

frequency
frequency is where on the radio dial the station can be heard. If the band is AM, the frequency will be between 540 and 1600. If the band is FM, the frequency will be between 87.8 and 108.0.

name
name is the name of the station returned. In most cases, this will be the same as callLetters combined with band. When returning networks, it will return the network name (e.g. Minnesota Public Radio).

tagline
The tagline is a short text-logo for the station.

market_city
marketCity is the city that the station is most closely associated with. This may or may not be the city the station is licensed in and it may or may not be the city that the station or the station's antenna is located in.

homepage
homepage is the station website.
Deprecated: Please retrieve the URL of type_id 1 (Organization Home Page) from the urls collection. This element may be removed in a future release of the Station Finder API.

donation_url
donation_url is a website where users may make a donation to support the station.
Deprecated: Please retrieve the URL of type_id 4 (Pledge Page) from the urls collection. This element may be removed in a future release of the Station Finder API.

logo
logo is the URL of an image associated with the station.
Deprecated: Please retrieve the URL of type_id 18 (Station Logo) from the urls collection. This element may be removed in a future release of the Station Finder API.

signal
The signal element specifies the strength of the signal for that station relative to the geographic search parameter. The relative parameter will contain a numeric representation of the signal strength while the value for the element will represent it in English. For searches not based on geographic parameters (e.g. call letters) strong is returned. The possible values are as follows:

5 - Strong
3 - Medium
1 - Weak

urls
For each station, there are many URL's of various types returned in a collection. Each item in the collection contains type_id, type_name, title, and href. The title is the link text, provided by the station, for the url. The definitions for the type_id and type_name for each URL are as follows:

1 - Organization Home Page
2 - Program Schedule
3 - Online Store
4 - Pledge page
5 - E-Newsletter
6 - Local News
7 - Audio Stream Landing Page
8 - RSS feed
9 - Podcast
10 - Audio MP3 Stream
11 - Audio Windows Media Stream
12 - Audio Real Media Stream
13 - Audio AAC Stream
14 - Video Podcast
15 - Newscast
16 - Facebook Url
17 - Twitter Feed
18 - Station Logo
19 - Stream Logo
20 - Station ID NPR One Audio Intro
21 - Station Hello Audio
22 - Station Sonic ID Audio
23 - Station NPR One Logo
24 - Station Identifier Audio - MP3
25 - Station Identifier Audio - ACC