NPR API How-to

There were some requests on the AIR Daily maillist for a quick&dirty how-to on using NPR’s new API. Your most common use will probably be embedding a single story into your web page or blog post.

Find the story at, then grab the url, e.g. this recent HV piece:

Copy the above storyID at the end of the url, and paste it into the JavaScript code below where it sez “PasteStoryIDHere”; also paste in your NPR API Key at “PasteYourAPIKeyHere” (instructions below on how to get one):

<script type="text/javascript" src=",&fields=title,teaser,storyDate,show,audio&output=JS&apiKey=PasteYourAPIKeyHere"></script>

Now paste all the above into your page/post, and it’ll display like this:

To display more than one story, list each ID, separated by a comma; e.g., the ID’s of these recent Jack Chance encounters: used in this code: <script type="text/javascript" src=",88961745&fields=title,teaser,storyDate,show,audio&output=JS&apiKey=PasteYourAPIKeyHere"></script> look like this:


Notice I’ve specified the fields=title,teaser,storyDate,show,audio. Those fields determine what’ll show on the page: you can remove some, or add others. The list of what’s possible is under the FIELDS tab of NPR’s Query Generator.

While there, check out the many other possibilities for interacting with NPR database of stories, audio, text, and photos. You can specify search terms, NPR shows, topics, and a host of other criteria for creating custom lists. And you can see how the lists will display. If there’s demand I’ll add another how-to sometime on using the Query Generator. (UPDATE: QG how-to added.)

To get an NPR API Key, start here:

Click the upper-left Register link to start your account. Or, if you subscribe to an NPR newsletter, you already have an account: click instead the upper-left Login link and enter your NPR subscription email and password.

Once in, click the Manage link in the upper-left. Copy it. (You can get it again anytime by returning to your account settings, and using the Open API top tab.)

Update: also see post for NPR API Query Generator.

Bookmark and Share
« | HV NEWS | »
Comments (4)

Thanks bg,

I can see this is something I’ll use right away.

I’ve tried using the Query Generator to give me a list of stories on say, US immigrants, but the code that is generated is really dense. It’s hard to see (and possible or not to sort) what gets returned.

I’d love to see a How To on the QG. When you have a minute.

Catherine Stifter

Comment added by Catherine Stifter on 07.24.08

[…] In response to Catherine’s comment: […]

Thanks for these instructions for manually placing content on a site, using NPR’s API.

Is there some info you might give me to place automatically, dynamically generating and updating content on the site, like you can with the Javascript modules that are available on the NPR stations site?

This is great for manual update and control of exactly which article I might want to display, but for many areas of my site manual updating would not be appropriate.

Thanks, WCW

Comment added by Willow Wright on 03.25.09

WCW, for dynamically generating content try the Query Generator:

here’s some info i kicked out on it:

the content will have to match one of the npr-defined categories, among them: programs, series, topic, or search terms.

so it’s according to what the parameters are for the content you wanna display, but the Query Generator should be able to get you there.

for instance here’s our widget for dynamically displaying series at NPR made by independent producers:

that and other widgets are at:

Comment added by BG on 03.25.09

Leave a comment:


(required) (will be hidden)

(Allowed tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> )