Context: This document is based on information found at  http://www.npr.org/api/index.php and my own use of the NPR API.  (The API Reference will be published separately.) —Gale Naylor 2016

National Public Radio API

Getting Started Guide


Use the NPR API to access information about stories presented on NPR and affiliate stations. Customize the fields returned and format the output as XML, HTML, JSON, RSS, or other formats.

Overview and Introduction

The archives of National Public Radio (NPR) contain digital content accessible through the NPR API. (A web interface also presents a subset of the content.)

According to the NPR website:

The content that is available includes audio from most NPR programs dating back to 1995 as well as text, images and other web-only content from NPR and NPR member stations. This archive consists of over 250,000 stories that are grouped into more than 5,000 different aggregations.

The NPR API exposes two endpoints for accessing content: a list endpoint and a query endpoint. The NPR documentation refers to the list endpoint as the List API and the query endpoint as the Story API (and also as a Query Generator). This document will use the terms list endpoint and query endpoint.

The list endpoint returns lists of content types, such as topics or programs, from the NPR archives. For example, /list?id=3002 returns a list of all topics and their corresponding ids. (See API Reference for the list of content type ids.) Also, the Mapping Index contains a comprehensive list of all ids, therefore using the list endpoint can be optional.

The query endpoint uses ids to access data from the NPR archives. Through the query endpoint you can search for stories on selected topics; search within specific programs, blogs, or series; search the biographies of selected NPR personalities, or search for stories about selected music artists. You can also refine your search, tailor the output, and change output formats.

NPR API Functional Diagram

ListEndpoint2.png

QueryEndpoint2.png

Getting Started

Although you can use the list endpoint without one, an API key is required to retrieve digital content from the NPR website. To obtain a key, register for an account. Registering is free.

The following Hello World tutorials will help you get started using the API. The NPR web interface also has a Query Generator that can be used to search NPR’s digital content, although it has limited access to content. Also, the NPR Mapping Index contains a comprehensive “list of lists” available through the API.

helloworldprogression.png

Hello World #1: Retrieve a list of topics (no API key required)

Use the list endpoint to retrieve a list of all topics:by entering the following in your browser: http://www.npr.org/list?id=3002 (Note: GET verb is required if not using a browser.)

Sample results:

<list id="3002" typeid="3002">

<title>All Topics</title>

<item id="1149" num="1" type="topic">

<title>Afghanistan</title>

<additionalInfo>Afghanistan</additionalInfo>

</item>

<item id="1126" num="2" type="topic">

<title>Africa</title>

<additionalInfo>Africa</additionalInfo>

</item>

<item id="1059" num="3" type="topic">

<title>Analysis</title>

<additionalInfo>

Analysis by NPR commentators, including Ted Koppel. Subscribe to our free podcast.

</additionalInfo>

</item>

See the API reference for a complete list of valid category ids.

Hello World #2: Retrieve a story (API key required)

Retrieve a list of Education stories from August 2016 that include the word “brain” in the story summary, and that have one or more images. Only display selected fields.

  1. Use the list endpoint (Hello World #1) to retrieve the Education topic id (id=”1013”) from the list of all topics:
    ...

<item id="1013" num="26" type="topic">

<title>Education</title>

<additionalInfo>

NPR news and commentary on education, schools, colleges and universities, and emerging trends in learning. Listen to audio and subscribe to RSS feeds.

</additionalInfo>

</item>
...

  1. Use the query endpoint to retrieve a link to the story:

http://api.npr.org/query?id=1013&fields=title,storyDate&requiredAssets=image
&startDate=8/1/2016&endDate=8/31/2016&searchTerm=brain&dateType=story
&output=NPRML&searchType=mainText&apiKey
={YourApiKey}

Sample results:

Use either the HTML link or the API link to access the story.
        ...

<nprml version="0.94">

<list>

<title>

<![CDATA[ NPR Topics: Education ]]>

</title>

<teaser>

<![CDATA[

NPR news and commentary on education, schools, colleges and universities, and emerging trends in learning. Listen to audio and subscribe to RSS feeds.

]]>

</teaser>

<miniTeaser/>

<link type="api">

http://api.npr.org/query?id=1013&searchTerm=brain&apiKey={YourApiKey}

</link>

<story id="486091892">

<link type="html">

http://www.npr.org/sections/ed/2016/08/18/486091892/the-amazing-pedal-powered-brain-race-the-finish-line?ft=nprml&f=1013

</link>

<link type="api">

http://api.npr.org/query?id=486091892&apiKey={YourApiKey}

</link>

<link type="short">http://n.pr/29HcveF</link>

<title>

<![CDATA[

The Amazing Pedal-Powered Brain Race: The Finish Line

]]>

</title>

<storyDate>Thu, 18 Aug 2016 06:01:00 -0400</storyDate>

</story>
...

Hello World #3: Change the output format

The default NPR XML format (NPRML) has the most features, but other output options are available.

Change to HTML: output=HTML

http://api.npr.org/query?id=1013&fields=title,storyDate,summary,image

&requiredAssets=image&startDate=8/1/2016&endDate=8/31/2016
&searchTerm=brain&dateType=story&output=HTML&searchType=mainText
&apiKey
={YourApiKey}

HTML Results:

Change to JSON: output=JSON

http://api.npr.org/query?id=1013&fields=title,storyDate,summary,image
&requiredAssets=image&startDate=8/1/2016&endDate=8/31/2016
&searchTerm=brain&dateType=story&output=JSON&searchType=mainText
&apiKey
={YourApiKey}

JSON Results:

{"version": "0.94", "list": {"title": {"$text": "NPR Topics: Education"}, "teaser": {"$text": "NPR news and commentary on education, schools, colleges and universities, and emerging trends in learning. Listen to audio and subscribe to RSS feeds."}, "miniTeaser": {}, "link": [{"type": "api", "$text": "http://api.npr.org/query?id=1013&searchTerm=brain&apiKey={YourAPIKey}"}], "story": [{"id": "486091892", "link": [{"type": "html", "$text": "http://www.npr.org/sections/ed/2016/08/18/486091892/the-amazing-pedal-powered-brain-race-the-finish-line?ft=nprml&f=1013"}, {"type": "api", "$text": "http://api.npr.org/query?id=486091892&apiKey={YourAPIKey}"}, {"type": "short", "$text": "http://n.pr/29HcveF"}], "title": {"$text": "The Amazing Pedal-Powered Brain Race: The Finish Line"}, "subtitle": {}, "shortTitle": {}, "teaser": {"$text": "These middle schoolers built a 200-pound human brain on wheels. Will it survive the eight-hour race through the streets of Baltimore?"}, "miniTeaser": {}, "slug": {"$text": "NPR Ed"}, "thumbnail": {"medium": {"$text": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_sq-6390786b6eb05e331d6dd7b2bd611e990423d98d.jpg?s=13"}, "large": {"$text": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_sq-6390786b6eb05e331d6dd7b2bd611e990423d98d.jpg?s=11"}, "provider": {"$text": "NPR"}}, "storyDate": {"$text": "Thu, 18 Aug 2016 06:01:00 -0400"}, "pubDate": {"$text": "Thu, 18 Aug 2016 09:08:00 -0400"}, "lastModifiedDate": {"$text": "Thu, 18 Aug 2016 09:08:39 -0400"}, "audioRunByDate": {}, "keywords": {}, "priorityKeywords": {}, "image": [{"id": "489772536", "type": "primary", "width": "200", "src": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_custom-82eaacd743b02d9114d3b505ddd5a0d985766635.jpg?s=12", "hasBorder": "false", "title": {"$text": "The Arbutus Middle School Kinetic Club rests during the Kinetic Sculpture Race in Baltimore. The students created and raced a foot-powered sculpture in a 15-mile race across downtown Baltimore on May 7."}, "caption": {"$text": "The Arbutus Middle School Kinetic Club rests during the Kinetic Sculpture Race in Baltimore. The students created and raced a foot-powered sculpture in a 15-mile race across downtown Baltimore on May 7."}, "link": {"url": ""}, "producer": {"$text": "Emily Bogle"}, "provider": {"url": "", "$text": "NPR"}, "copyright": {}, "enlargement": {"src": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_custom-82eaacd743b02d9114d3b505ddd5a0d985766635.jpg", "caption": {}}, "crop": [{"type": "standard", "src": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit-a3b520f29c55824e9f3fdf01e52d92de4b1b593e.jpg", "height": "1998", "width": "2664"}, {"type": "square", "src": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_sq-6390786b6eb05e331d6dd7b2bd611e990423d98d.jpg", "height": "1215", "width": "1215"}, {"type": "wide", "src": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_wide-0c0878992286d4aebfd32c9afa064ef46f5e07e0.jpg", "height": "1687", "width": "3000"}, {"type": "enlargement", "src": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_custom-82eaacd743b02d9114d3b505ddd5a0d985766635.jpg", "height": "1998", "width": "3000"}, {"type": "custom", "src": "https://media.npr.org/assets/img/2016/08/12/arbutuskinetic-2016-05-09-1779-edit_custom-82eaacd743b02d9114d3b505ddd5a0d985766635.jpg", "height": "1998", "width": "3000", "primary": "true"}]}]},
...