Story API

The Story API was NPR’s first – and still most popular – API. The Story API returns stories from NPR’s on-air programs and NPR.org. The Story API is the workhorse that sends NPR’s stories to mobile devices, connected cars, and NPR member station sites.

Registration and Terms of Use

To use this API, you’ll need to register for a key. By registering, you’re consenting to our full Terms of Use. You should read them all, but here are some highlights.

Quick Start

The story API is an ID-based API, and each ID returns stories grouped by their assigned metadata, which includes: reporter bylines, assigned topics, assigned special series, and NPR programs affiliation.

Every reporter, program, topic, music artist, music genre, and series aggregation has its own numeric ID.

# Return latest stories from the Science main topic (id=1007) 
GET http://api.npr.org/query?id=1007&apiKey=YOUR_KEY

# Return latest stories from the 'All Things Considered' program (id=2)
GET http://api.npr.org/query?id=2&apiKey=YOUR_KEY      

Tip: the quickest way to get fluent in the Story API is to use the Query Generator.

You can also pass in comma-delimited ID’s. The default action is an intersection (AND).

 # Science stories (id=1007) written by NPR reporter Joe Palca (id=2101004). 
 GET http://api.npr.org/query?id=1007,2101004&apiKey=YOUR_KEY

You can even pass in the ID of an individual story to just query that story. NPR.org’s story page URLs from summer 2010 onward look like this:

http://www.npr.org/YYYY/MM/DD/[:id]/story-title

For this story:

http://www.npr.org/2012/08/10/158515499/so-you-landed-on-mars-now-what 

the ID is 158515499.

Older stories have their ID in the query string:

http://www.npr.org/templates/story/story.php?storyId=[:id] 

All stories have a title, a teaser description, and a publish date. Stories may contain one or more content resources, such as audio, text, images, and multimedia.

You can filter the return to only include stories that contain certain content resources. For good measure, let’s also set a maximum of 20 stories returned

# Science stories with audio (requiredAssets=audio). 20 results max (numResults=20)
GET http://api.npr.org/query?id=1007&apiKey=YOUR_KEY&requiredAssets=audio&numResults=20

That, in a nutshell, is the Story API. Go experiment with the Query Generator and tell us what you come up with!

Want to learn more? Take the NPR API course on Codecademy.

Accessing the API

Each call is made to the API via a simple HTTP GET request. The URL should contain a URL path and appended query parameters and values. The URL path of the Story API is http://api.npr.org/query?. Query parameters should follow a question mark.

Example:

GET http://api.npr.org/query?id=1007,3&numResults=10

The API supports many output formats. JSON and NPRML, NPR’s custom XML format, are the two formats that contain all story resouces and metadata. We also support many standard formats that are simple to use, though do not contain full story information: RSS, MediaRSS, ATOM, HTML, and JavaScript widgets. Note: ATOM, HTML, and Javascript widgets will be retired in the next version of the Story API.

Input Parameters

The input parameters tell the API what stories to return and how to return them. There are four types of parameters (Access Parameters, Data Parameters, Output Parameters and Control Parameters). Each of the parameters from the four types are described below:

Access Parameters

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.

Data Parameters

id
Returns stories that belong to the provided IDs. Lists of IDs must be comma-delimited (e.g.: id=1001,2). At least one ID is required for all queries, unless the query is using searchTerm.
date
Returns stories with the exact date requested. Date format is supplied in: YYYY-MM-DD format (e.g.: July 22nd, 2012 would be: 2012-07-22). The special value: date=current is also allowed. If one of the id parameters is a program, this will return stories from the last complete episode of that program. If none of the id parameters belong to a program, then date=current will return stories from today. date=currentWithAudio is a special parameter that can only be used with a program id and will return the last full episode of the given program that contains complete audio. If the current day’s program episode is not complete with audio, the prior day’s episode will return. Date parameter cannot be used with startDate or endDate.
startDate
Returns stories with a story date later than or equal to the startDate. Can be used with endDate to return stories within a date range; dateType can modify the meaning of this parameter
endDate
Returns stories with a story date earlier than or equal to the endDate. Can be used with startDate to return stories within a date range; dateType can modify the meaning of this parameter
orgId
Returns stories that are provided by the selected organization. Owner organizations primarily include NPR and NPR member stations.
searchTerm
Returns stories that are considered matches to the searchTerm based on NPR’s search engine. Can be used with searchType to inform the search engine which fields it should search.
searchType
Used with searchTerm to inform the search engine which fields it should search. Default is to search the full content of the story (full text, transcripts, etc). For a more targeted search, use something like: searchTerm=mainText, which tells the search engine to search only title and teaser fields for the story. This parameter must be used with the searchTerm parameter.

Output Parameters

meta

Controls the meta information for the API call. The meta information is described in greater detail in the Meta Information section of the Output Reference. The meta parameter can receive “none”, “inherit” or “default”. None will suppress the meta information completely. Inherit will mirror, to the extent possible, the fields requested by the fields parameter. Default, which is the same as not passing in the meta parameter at all, will return the title, teaser and miniTeaser for the API call.

output

The output parameter tells the API what the desired output format should be for the results. The default format is NPRML (NPR’s custom XML format), but other formats including: RSS, MediaRSS, Atom and JSON can also be requested. For more details on the various output formats, go to the Output Reference. The API allows users to select RSS, for example, while extending the namespace to include fields beyond the standard RSS fields. Those extended namespace fields will be returned in NPRML.

Various values allowed as the value of the output parameter and their meaning are as follows:

output.NPRML
NPRML is the default output structure for the document. To learn more about NPRML, see our Output Reference and Message Reference.
output.RSS
Setting output to RSS will return the results in the standard RSS 2.0 format. To learn more about RSS, see RSS 2.0 Specification.
output.MediaRSS
Setting output to MediaRSS will return the results in standard RSS 2.0 format with the MediaRSS extensions. RSS will be extended for audio and image assets. Currently, video is not supported by the API. To learn more about MediaRSS, see the Media RSS Specification.
output.Podcast
Setting output to Podcastwill return the results in standard RSS 2.0 format with the Podcast extensions, including an MP3 audio enclosure. For audio that NPR does not have the rights to offer as downloadable audio, these stories will be automatically suppressed from the output.
output.ATOM
Setting output to ATOM will return the results in standard Atom format. To learn more about Atom, go to Atom Enabled.
output.JSON
Setting output to JSON will return NPRML results in a JSON format. To learn more about JSON, see the JSON Specification.
output.HTML
Setting output to HTML will return the results in a limited HTML formatted block. The limitations are in the content as its fields are not configurable and we will only return title, date, teaser, the link to the story, and links to the MP3, Real Audio and Windows Media audio (to the extent that they are available).
output.JS
Setting output to JS will return the results in a limited HTML formatted block that has been wrapped around a JavaScript document.write statement. The limitations are in the content as its fields are not configurable and we will only return title, date, teaser, the link to the story, and links to the MP3, Real Audio and Windows Media audio (to the extent that they are available).
fields

The fields parameter tells the API which fields to return in the output for the results. For NPRML, you can pick and choose any combination of fields. For other formats, the standard fields for that format will be returned, although you can extend the namespace beyond the standard by selecting other fields. To see a complete list of possible fields, go to the Query Generator and click on the Fields tab.

fields.title
Includes the title of the story. A title exists for all stories.
fields.teaser
Includes the teaser of the story. A teaser exists for all stories.
fields.storyDate
Includes the date of the story. A date exists for all stories.
fields.show
Includes all program associations of the story. Not all stories are associated with a program.
fields.byline
Includes all credited contributors of the story. Not all stories have credited contributors.
fields.text
Includes the full text of the story. This field contains no markup in it - it is just the pure text. Not all stories have full text.
fields.audio
Includes all audio assets of the story (to the extent that we can distributed them). Not all stories have audio assets, although the vast majority of stories do.
fields.image
Includes all image assets of the story (to the extent that we can distributed them). Not all stories have image assets.
fields.textWithHtml
Includes the full text of the story. This field contains all of the editorially applied HTML to add styles to the content (such as bolding text, URLs embedded in the text, etc.). Not all stories have full text.
fields.listText
Includes any lists or text extensions of the story. This fields is used in a variety of ways and is used to enrich the story by providing timelines, story summaries, extended information about the story, etc. Not all stories have list text.
fields.pullQuote
Includes any isolated quotes of the story. Not all stories have pull quotes.
fields.parent
Includes all relationships between the story and any list to which it belongs. Not all stories have parents.
fields.relatedLink
Includes all relationships of the story to other stories on NPR.org or to web pages on other sites. Not all stories have related links.
fields.album
Includes all albums associated with the story. Not all stories have album associations.
fields.artist Includes all musical artists associated with the story. Not all stories have artist associations.
fields.product
Includes all purchasable products associated with the story. Not all stories have product associations.
fields.transcript
Includes a link to the transcript API, if a transcript is available for this story.
fields.correction
Includes information about any correction to the story, such as (possibly empty) title, text, and date.
fields.all
All is the default setting for NPRML if the fields parameter is not explicitly used. All returns every field that is available for the story.
fields.none
Excludes all content fields and will only return the id and links associated with any results.
fields.summary
Shorthand for an aggregation of specific fields, including title, subtitle, shortTitle, teaser, miniTeaser, slug, thumbnail, toenail, storyDate, pubDate, lastModifiedDate, keywords, and priorityKeywords. Some of these parameters can only be seen using the summary or all options in the fields parameter.
fields.titles
Returns all titles, including title, subtitle, shortTitle, and slug.
fields.teasers
Returns all teasers, including teaser and miniTeaser.
fields.dates
Returns all dates, including storyDate, pubDate, and lastModifiedDate.
fields.collection
Optionally used on story pages to order story subelements in a list-type structure, the collection is the container that specifies ordering for child member elements. Common usages are denoted by displayType and include music lists, book lists, and photo galleries. Collections have child member elements with a numeric ordering and a refid that corresponds to the individual members.
fields.member
Contains the content for a given member that is a child of a collection element. Member id attribute maps directly to a refid for a given collection and can be used to determine member order.
callback
This parameter is only used with JSON output. If callback is not specified, JSON output contains the JSON-object representing the results. If callback is specified, then the JSON-object is wrapped in a callback function that is named with the value of this parameter. This allows the user to define how the response is handled in their code and works-around the same-domain origination policy of Javascript.

Control Parameters

sort

Determines the order in which the stories will be returned. Options include:

  • dateAsc - date descending,
  • dateDesc - date descending,
  • assigned - editor assigned,
  • featured - will put the featured stories for a show at the top of the result list; it is only useful if a program ID is included in the list of ID parameters in the query
  • relevance - ordered by the relevance of search results. Useful for search queries.

Default sort order is date descending.

startNum

Used for pagination of results, startNum tells the API where in the result set to start returning stories. If not used with numResults, the API will return up to 20 stories. If numResults is specified, the API will return the specified number of results. This allows for requests of stories 1-20, 21-40, 41-60, etc.

numResults

Restricts the number of stories returned by the API. The default value of number of stories returned is 20. If numResults is a number greater than the maximum, the API will return the maximum. Can be used with startNum to paginate through results. This allows for requests of stories 1-20, 21-40, 41-60, etc.

action

Informs the API how to treat a list of IDs passed in through the id parameter. Using “or” means that stories that appear in any of the IDs will be returned. Using “and”, or omission of the action parameter means that only stories that appear in all of the IDs will be returned. Using “union” will return results as though from a separate query for each ID.

For example:

id=10001,10003&action=union&numResults=3

would return up to six stories, since it’s the sum of both id=10001&numResults=3 and id=10003&numResults=3.

requiredAssets

Limits the result set to contain only stories with a particular type of asset. Allowed values are:

  • audio
  • image
  • text
  • correction

You can specify more than one required asset by separating the values with commas. For example: requiredAssets=image,audio,text,correction would return only stories that contain images and audio and text and which have been corrected after publication.

dateType

Controls the meaning of startDate and endDate.

  • dateType.story - Date parameters refer to the story date. This is the default.
  • dateType.correction - Date parameters refer to the correction date. (Implies requiredAssets.correction)
title

Changes the title of the feed at the list level. This parameter is optional. If this parameter is ommited, the system will provide the default title for the requested feed.

Ingest and Permissions

NPR member stations may publish or “ingest” their content to the Story API and use permissions to control which organizations may retrieve that content.

Both publishing to the API and permissions are fully handled by NPR’s Core Publisher CMS. For stations using the API on their own who want to ingest or control permissions, please contact NPR Digital Services for instructions.

Story Lists API

What we call “Lists” in the NPR API is a collection of NPR stories that represent a given topic or subject matter (e.g.: Health Care, Interviews). Following is a definition of the various list types available in the API along with the URLs to access these lists.

  1. Topics: — Collection of NPR stories that represent a given topic or subject matter. (eg. Health Care, Interviews)

    All Topics: GET http://api.npr.org/list?id=3002

    All Topics and Music Genres: GET http://api.npr.org/list?id=3218

  2. Music Genres: — Collection of NPR stories that represent a given musical genre. (eg. Rock/Pop/Folk, Jazz)

    All Music Genres: GET http://api.npr.org/list?id=3018

    All Topics and Music Genres: GET http://api.npr.org/list?id=3218

  3. Programs: Collection of NPR stories that aired on an NPR program. (eg. All Things Considered, Tell Me More)

    All Programs: GET http://api.npr.org/list?id=3004

  4. Bios: Collection of NPR stories as reported by an NPR personality. Personalities are sorted by letter. (eg. Nina Totenburg, Steve Inskeep)

    All Personalities: GET http://api.npr.org/list?id=3007

  5. Music Artists: Collection of stories that are about music artists. Artists are sorted by letter. (eg. Bob Dylan, Death Cab For Cutie)

    All Recently Featured Music Artists: GET http://api.npr.org/list?id=3008

    All Music Artists: GET http://api.npr.org/list?id=3009

  6. Columns: Collection of stories containing opinions and perspectives of an NPR personality. (eg. Watching Washington, Song of the Day)

    All Columns: GET http://api.npr.org/list?id=3003

  7. Series: An ongoing collection of NPR stories on a topic. (eg. Climate Connections, Summer Books)

    All Recent Series : GET http://api.npr.org/list?id=3006

  8. Blogs: Collection of posts on a theme. (eg. Inside NPR.org, All Tech Considered)

    All Blogs: GET http://api.npr.org/list?id=3013

  9. Categories: A short description for a blog. (eg. Editorial, API, or Audience Estimates for the blog Inside NPR.org). Requires a blog ID, found via All Blogs, above.

    All Categories for Inside NPR.org: GET http://api.npr.org/list?typeId=3132&id=91000411

  10. Tags: A short description for a blog post. (eg. actors, approval rating, feedback, zombies)

    All Tags: GET http://api.npr.org/list?id=3024

List API Parameters

List parameters tell the List API which items to return and how to return them. There are two types of parameters (Data Parameters and Output Parameters). Each of the type of parameters is described below:

Data Parameters

childrenOf

Returns only items which are assigned to the given topic ID. For example:

?id=3006&childrenOf=1008

would return only recent series which are assigned to “Arts & Life”. This parameter is available for the lists All Topics and Recent Series

hideChildren

If set to “1”, returns only topics which are not subtopics of another topic. For example:

?id=3002&hideChildren=1

This parameter is only available for the All Topics list.

Output Parameters

output
If the output parameter is specified for a list, it currently has only one possible value: JSON. If it is not specified, the output will be list XML. This parameter is available for all lists.
output.JSON
Setting output to JSON will return list results in a JSON format. To learn more about JSON, see the JSON Specification.
callback
This parameter is only used with JSON output. If callback is not specified, JSON output contains the JSON-object representing the results. If callback is specified, then the JSON-object is wrapped in a callback function that is named with the value of this parameter. This allows the user to define how the response is handled in their code and works-around the same-domain origination policy of Javascript. This parameter is available for all lists.

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

  GET http://api.npr.org/stations?callLetters=WAMU&apiKey=demo  

Search by zip code

GET http://api.npr.org/stations?zip=20902&apiKey=demo  

Search by city/state

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

Search by latitude/longitude

GET http://api.npr.org/stations?lat=37.22987&lon=80.41769&apiKey=demo  

Search by organization ID

 GET http://api.npr.org/stations?id=202&apiKey=demo

JSON Output Example

{
   version: '0.94',
   title: {
      $text: 'WAMU'
   },
   station: [
      {
         id: '305',
         callLetters: {
            $text: 'WAMU'
         },
         band: {
            $text: 'FM'
         },
         name: {
            $text: 'WAMU-FM'
         },
         memberStatus: {
            $text: 'Member'
         },
         frequency: {
            $text: '88.5'
         },
         marketCity: {
            $text: 'Washington'
         },
         state: {
            $text: 'DC'
         },
         url: [
            {
               typeId: '1',
               type: 'Organization Home Page',
               title: 'WAMU Homepage',
               $text: 'http://wamu.org'
            },
            {
               typeId: '2',
               type: 'Program Schedule',
               title: 'Program Schedule',
               $text: 'http://wamu.org/programs/schedule/'
            },
            {
               typeId: '4',
               type: 'Pledge Page',
               title: 'Support  WAMU',
               $text: 'http://wamu.org/support/membership/campaign/'
            },
            {
               typeId: '7',
               type: 'Audio Stream',
               title: 'Listen Online',
               $text: 'http://wamu.org/listen'
            },
            {
               typeId: '7',
               type: 'Audio Stream',
               title: 'WAMU 88.5 (HD 88.5-1)',
               $text: 'http://wamu.org/listen/'
            },
            {
               typeId: '7',
               type: 'Audio Stream',
               title: 'WAMU\'s Bluegrass Country',
               $text: 'http://bluegrasscountry.org/'
            },
            {
               typeId: '7',
               type: 'Audio Stream',
               title: 'Intersection 88.5-3',
               $text: 'http://wamu.org/listen/'
            },
            {
               typeId: '9',
               type: 'Podcast',
               title: 'The Animal House from WAMU 88.5',
               $text: 'http://feeds.feedburner.com/WAMU885TheAnimalHouse'
            },
            {
               typeId: '9',
               type: 'Podcast',
               title: 'The Diane Rehm Show: Friday News Roundup',
               $text: 'http://www.npr.org/templates/rss/podcast.php?id=510024'
            },
            {
               typeId: '9',
               type: 'Podcast',
               title: 'WAMU: Metro Connection',
               $text: 'http://www.npr.org/templates/rss/podcast.php?id=510081'
            },
            {
               typeId: '9',
               type: 'Podcast',
               title: 'WAMU: The Diane Rehm Show',
               $text: 'http://www.npr.org/templates/rss/podcast.php?id=510071'
            },
            {
               typeId: '9',
               type: 'Podcast',
               title: 'WAMU: The Kojo Nnamdi Show',
               $text: 'http://www.npr.org/templates/rss/podcast.php?id=510206'
            },
            {
               typeId: '9',
               type: 'Podcast',
               title: 'WAMU: The Kojo Nnamdi Show: Tech Tuesday',
               $text: 'http://www.npr.org/templates/rss/podcast.php?id=510025'
            },
            {
               typeId: '9',
               type: 'Podcast',
               title: 'WAMU: The Politics Hour',
               $text: 'http://www.npr.org/templates/rss/podcast.php?id=510207'
            },
            {
               typeId: '10',
               type: 'Audio MP3 Stream',
               title: 'WAMU 88.5 (HD 88.5-1)',
               $text: 'http://wamu.org/streams/npr/wamu-1.pls'
            },
            {
               typeId: '10',
               type: 'Audio MP3 Stream',
               title: 'Intersection 88.5-3',
               $text: 'http://wamu.org/streams/npr/wamu-3.pls'
            },
            {
               typeId: '10',
               type: 'Audio MP3 Stream',
               title: 'WAMU\'s Bluegrass Country',
               $text: 'http://www.npr.org/burnedPages/xml/localize/music/wamu.pls'
            },
            {
               typeId: '11',
               type: 'Audio Windows Media Stream',
               title: 'WAMU\'s Bluegrass Country',
               $text: 'http://wamu-wm.streamguys.com/WAMU-2'
            },
            {
               typeId: '15',
               type: 'Newscast',
               title: 'WAMU-FM News',
               $text: 'http://downloads.wamu.org/wamunews.mp3'
            },
            {
               typeId: '16',
               type: 'Facebook Url',
               title: 'Facebook',
               $text: 'http://www.facebook.com/wamu885'
            },
            {
               typeId: '17',
               type: 'Twitter Feed',
               title: 'Twitter',
               $text: 'http://twitter.com/wamu885'
            }
         ],
         image: [
            {
               type: 'logo',
               $text: 'http://media.npr.org/images/stations/logos/wamu_fm.gif'
            }
         ],
         tagline: [
            {
               $text: 'The Mind Is Our Medium'
            }
         ],
         orgDisplayName: {
            $text: 'WAMU'
         }
      }
   ]
}

XML Output Example

<station id="305">
  <callLetters>WAMU</callLetters>
  <band>FM</band>
  <name>WAMU-FM</name>
  <frequency>88.5</frequency>
  <marketCity>Washington</marketCity>
  <signal relative="5">strong</signal>
  <url typeId="1" type="Organization Home Page" title="WAMU 88.5 Homepage">http://wamu.org</url>
  <url typeId="2" type="Program Schedule" title="Program Schedule">http://wamu.org/programs/schedule/</url>
  <url typeId="4" type="Pledge Page" title="Support WAMU">http://www.wamu.org/support/membership/campaign/</url>
  <url typeId="7" type="Audio Stream" title="Listen to WAMU 88.5">http://wamu.org/listen/</url>
  <url typeId="9" type="Podcast" title="WAMU: Metro Connection">http://www.npr.org/templates/rss/podcast.php?id=510081</url>
  <url typeId="9" type="Podcast" title="The Diane Rehm Show: Friday News Roundup">http://www.npr.org/templates/rss/podcast.php?id=510024</url>
  <url typeId="9" type="Podcast" title="WAMU: The Kojo Nnamdi Show">http://www.npr.org/templates/rss/podcast.php?id=510206</url>
  <url typeId="9" type="Podcast" title="WAMU: The Politics Hour">http://www.npr.org/templates/rss/podcast.php?id=510207</url>
  <image type="logo">http://media.npr.org/images/stations/logos/wamu_fm.gif</image>
  <tagline>Your NPR News Station In the Nation's Capital</tagline>
</station>

Station Finder Output Example

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 bandare 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 elements 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.

Transcripts API

The Transcript API provides access to full transcripts of stories airing on selected NPR programs. Note: NPR transcripts are created on a rush deadline by a contractor for NPR, and accuracy and availability may vary. This text may not be in its final form and may be updated or revised in the future. Please be aware that the authoritative record of NPR’s programming is the audio.<

Transcript API Reference

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

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.
id
Story ID of the story for which you want a transcript.

Transcript API Example

Besides the api key, the only parameter for Transcript API calls is the id. The id will be the same id number that is used in the Story API and in the URL of story pages on NPR.org:

http://api.npr.org/transcript?id=10192781&apiKey=demo

Sample Output:

    <transcript>
      <link type="html">http://www-rd.npr.org/templates/transcript/transcript.php?storyId=10192781</link>
      <link type="api">http://api-rd.npr.org/transcript?id=10192781&apiKey=MDAwMTAwMDIxMDEyMTYyMTc4MzA4YmJlMg010</link>
      <story id="10192781">
        <link type="html">http://www-rd.npr.org/templates/story/story.php?storyId=10192781</link>
        <link type="api">http://api-rd.npr.org/query?id=10192781&apiKey=MDAwMTAwMDIxMDEyMTYyMTc4MzA4YmJlMg010</link>

      </story>
      <paragraph num="1"><![CDATA[MICHELE NORRIS, host: ]]></paragraph>
      <paragraph num="2"><![CDATA[The nominees for Broadway's Tony Awards were announced this morning. Leading the pack was the musical "Spring Awakening" with 11 nominations. But it's crowded at the top. Bob Mondello reports two other shows had 10 nominations each. ]]></paragraph>
      <paragraph num="3"><![CDATA[BOB MONDELLO: Teenagers with raging hormones are ideal subjects for a rock musical but these teenagers hail from the 19th century. ]]></paragraph>
      <paragraph num="4"><![CDATA[(Soundbite of Broadway play, "Spring Awakening") ]]></paragraph>
      <paragraph num="5"><![CDATA[Unidentified Man #1: (Singing) This night is like that fantastic tossing and turning without rest because my days at the piano with my teacher and her breast. ]]></paragraph>
      <paragraph num="6"><![CDATA[MONDELLO: "Spring Awakening," a rambunctious ultimately tragic tale of teens in the 1800s who know less than they need to know about sex was nominated for Best Musical, Best Score, Best Book, Best Actor and six other Tonys. And close behind with 10 nominations was an equally unconventional show, "Grey Gardens," a musical based on a famous documentary about a pair of eccentric, reclusive relatives of First Lady Jacqueline Kennedy. ]]></paragraph>
      <paragraph num="7"><![CDATA[(Soundbite of Broadway play, "Grey Gardens") ]]></paragraph>
      <paragraph num="8"><![CDATA[Unidentified Woman: I found your pet cat, my darling. ]]></paragraph>

      <paragraph num="9"><![CDATA[Unidentified Man #2: Meow. ]]></paragraph>
      <paragraph num="10"><![CDATA[Unidentified Woman: I think it's that time the light looks fading. It's a pet tale that sends shivers to the cats. ]]></paragraph>
      <paragraph num="11"><![CDATA[Unidentified Man #3: Meow. ]]></paragraph>
      <paragraph num="12"><![CDATA[Unidentified Man #4: Meow. ]]></paragraph>
      <paragraph num="13"><![CDATA[Unidentified Group #1: Meow. ]]></paragraph>
      <paragraph num="14"><![CDATA[Unidentified Group #2: (Singing) The fog will clear and there it stays. It's on a cage - the house in Hades. ]]></paragraph>
      <paragraph num="15"><![CDATA[MONDELLO: Also nominated for Best Musical are "Curtains," a murder-mystery spoof with a score by John Kander and Fred Ebb, a team that already has a shelf full of Tonys for "Cabaret" and "Chicago," and a stage version of the Disney classic "Mary Poppins." Not nominated for Best Musical but a contender for seven other awards is the splashy, pink just opened "Legally Blonde," yet another film-to-stage transplant. ]]></paragraph>
      <paragraph num="16"><![CDATA[Tony nominees in the Best Play category include the docudrama "Frost/Nixon," which brings TV to the stage in the form of David Frost's interviews with Richard Nixon; "Radio Golf," the final installment in August Wilson's 10-play cycle about the African-American experience in the 20th century; "The Little Dog Laughed," a recently closed show about a closeted gay film star; and the Tom Stoppard epic trilogy, "The Coast of Utopia." ]]></paragraph>
      <paragraph num="17"><![CDATA[(Soundbite of Broadway play, "The Coast of Utopia") ]]></paragraph>

      <paragraph num="18"><![CDATA[Unidentified Man #5: I give you a toast - the liberty of each for the equality of all. ]]></paragraph>
      <paragraph num="19"><![CDATA[Unidentified Group #3: The liberty of each for the equality of all. ]]></paragraph>
      <paragraph num="20"><![CDATA[Unidentified Man #5: What does that mean - it doesn't mean anything. ]]></paragraph>
      <paragraph num="21"><![CDATA[MONDELLO: "The Coast of Utopia" has been a hit with both critics and audiences despite the fact that's it nearly nine hours long and is concerned with the thought processes of pre-revolutionary Russian intellectuals. That it should be nominated in lots of categories makes sense as it has an enormous cast and elaborate production effects. "The Coast of Utopia" is nominated for 10 awards - five of them for acting, which may be why a number of bankable stars in other shows including Kevin Spacey, Nathan Lane and Brian Dennehy didn't make the cut. But Angela Lansbury, returning to Broadway after nearly a quarter of a century away, stands a decent chance of adding to the four Tonys she already has. This despite the fact that almost no one likes "Deuce," the play that's brought her back to New York. ]]></paragraph>
      <paragraph num="22"><![CDATA[The Broadway season has been a record-setter at the box office bringing in some $876 million in part because of ever-rising ticket prices all of which means a lot is riding on the Tony Awards which will be telecast on Sunday, June 10. ]]></paragraph>
      <paragraph num="23"><![CDATA[I'm Bob Mondello. ]]></paragraph>
      <paragraph num="24"><![CDATA[(Soundbite of music)  Transcript provided by NPR, Copyright National Public Radio.]]></paragraph>
    </transcript>

Transcript API Output Definitions

Below is a description for each of the elements returned by the Transcript API.

transcript
<transcript> is the top-level element that includes all results returned by the query.
link
<link> nodes provide links to other pages associated with this transcript.
The <link type="html"> node that is a direct descendant of <transcript> is a link to an HTML version of the transcript.
The <link type="api"> node that is a direct descendant of <transcript> is a link to the transcript API for this transcript. In other words, it is a self-referential link to this transcript result itself.
The <link type="html"> node that is a descendant of <story> is a link to the HTML page of the story related to this transcript.
The <link type="api"> node that is a descendant of <story> is a link to the story API for the story related to this transcript. This link will provide you access to story assets such as images and audio.
story
The <story> node contains links to the story related to this transcript. See link for more information.
paragraph
The <paragraph> nodes contain the actual text of the transcript. Note that the text is inside CDATA blocks.