| 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 or longitude/latitude. 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
 

The following get passed to the Station Finder API, as query string parameters on the base URL (http://api.npr.org/stations.php):

apiKey
The apiKey parameter is required for all API requests. To get a key, you must register. Once registered, you can get and/or change your apiKey from your Account Manager.
Upon registration, your apiKey will be saved to a cookie that will enable the Query Generator to apply your apiKey to your queries.

zip
Searches for stations that can be heard in the provided zip code.

city
Searches for stations that can be heard in the provided city/state. When using city, the state parameter must also be used.

state
Searches for stations that can be heard in the provided city/state. When using state, the city parameter must also be used.

callLetters
The call letters are the unique identifiers associated with the stations. This parameter searches for stations that have the provided call letters, or are related to the provided call letters. Can be used with the band parameter to refine the search.

band
The band indicates if the station is an FM or AM station. This parameter searches for stations that have the provided call letters AND band, or are related to the provided call letters AND band. This parameter must be used with the call letters parameter.

network
Searches for stations that belong to the provided network.

lat
Searches for stations that can be heard in the provided latitude/longitude. Both parameters are float values. This parameter must be used with the lon parameter. The system is always expecting the latitude to be a positive value.

lon
Searches for stations that can be heard in the provided latitude/longitude. Both parameters are float values. This parameter must be used with the lat parameter. The system is always expecting the longitude to be a positive value.

id
The unique ID associated with the organization.

 
Station Finder API Examples
 

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

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

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

Search by city/state
http://api.npr.org/stations?city=Silver+Spring&state=Maryland&apiKey=demo

Search by latitude/longitude
http://api.npr.org/stations?lat=37.22987&lon=80.41769&apiKey=demo

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

 
Station Finder Output Example
 


 
Station Finder Output Definitions
 

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

stations
< stations > is the top-level element that includes all stations returned from the query.

station
< station > is the parent element for all station-specific information returned. Each station returned will be presented inside its own < station > tag. The id parameter is always returned in the output and is the system's unique id for that station. The id parameter is the same as the orgId used in the Story API, representing the owner of the story.

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

band
See < callLetters >.

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).

translator_callLetters
Translators are antennas that allow the station to be heard in places that the station's primary antenna cannot reach. Many of the station results will not have the < translator_callLetters > or < translator_band > elements - for those cases, the results are primary radio antennas. If the translator elements are returned, however, it means that the station returned is the translator. In those cases, the values in the < callLetters > and < band > elements belong to the primary station antenna and the values in the < translator_callLetters > and < translator_band > elemenets are to the translator.

translator_band
See < translator_callLetters >.

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.

marketCity
< 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.

signal
The < signal > element specifies the strength of the signal for that station relative to the 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. The possible values are as follows:

5 - Strong
3 - Medium
1 - Weak

url
For each station, there can be many < url > elements. The < url > element will contain a typeId, type (which contains the name of the type), and the title. The title is the link text, provided by the station, for the url. The definitions for the typeId and type name are as follows:

0 - Station image logo
1 - Organization home page
2 - Program schedule
4 - Station pledge page
7 - Audio Stream
8 - RSS feed
9 - Podcast

image
< image > is in image associated with the station. The type parameter will indicate that the image is the station's logo.

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