Inside NPR.org

API

NPR API is Live on NPR.org

As referenced in yesterday's post, we launched our new API today. To find the API, you can either go directly to http://www.npr.org/api/ or you can follow the new link called "Tools / API" on the NPR.org left nav under the Services section.

In order to use the API, you will need to register using our new registration engine that Zach mentioned in a previous post. Once registered, you will need to generate an apiKey by clicking the Generate Key button on the API tab of your account profile. The apiKey is used to authenticate all requests to the API. After you get your apiKey, you can read our documentation or just go straight to the Query Generator, which is a comprehensive tool that allows you to easily create your API requests and see what your results would look like.

There were quite a few questions that we addressed when developing the API, but one thing that was not really in question was the need to open as much of our content as possible. As a result, almost everything that you can find on NPR.org that we have the rights to redistribute is available through the API. This includes audio, images, full text, etc. That said, there are elements, series and programs that we could not offer due to rights restrictions.

We also discussed in depth which output formats we would support. For launch, we are supporting RSS, MediaRSS, Atom, JSON, JavaScript Widgets, HTML Widgets and our custom tagging structure called NPRML. We would like feedback on what other formats we should support, although as of now we are planning to extend it to include NewsML. Which of the existing formats are you most likely to use from our API?

There were a ton of contributors to this new API with the primary technical architect being Harold Neal. Other major contributors include Joanne Garlow, Jason Grosman, Tony Yan, Ivan Lazarte, Stephanie Oura, Ben Hands, Shain Miley, Lindsay Mangum, Sugirtha Solai, Todd Welstein and Vida Logan, and others.

Finally, we would really like to get as much feedback from the community on the API, particularly on what you think you will use and what is missing from the offering. We will continue to post here with more thoughts and questions.

Comments

 

Please keep your community civil. All comments must follow the NPR.org Community rules and terms of use, and will be moderated prior to posting. NPR reserves the right to use the comments we receive, in whole or in part, and to use the commenter's name and location, in any medium. See also the Terms of Use, Privacy Policy and Community FAQ.

I "twittered" with excitement when I saw this.

Sent by Steve Petersen | 10:32 AM | 7-16-2008

the query generator is a stroke of genius.

Sent by Jason | 11:02 AM | 7-16-2008

Daniel should have listed himself as a contributor to the API--he is the father of the API, it is his brain child.

Sent by Harold Neal | 11:05 AM | 7-16-2008

This is a great opportunity to demonstrate how powerful "open" can be. Thanks.

Sent by krash63 | 12:21 PM | 7-16-2008

This is really exciting - thanks for taking the bold step to distribute content through an API!

Sent by Ryan Moede | 9:04 AM | 7-17-2008

Congrats Dan and team. I look forward to seeing NPR's wonderful content get remixed in all sorts of creative ways.

Sent by Rekha | 9:57 AM | 7-17-2008

Very cool. I'm sure some neat stuff will come from it.

Can I suggest that you investigate the use of XMPP for doing stuff with this API? The possibilities there are really cool. Check out some of the things that the BBC is doing with it as a starting point for ideas.

Sent by Jeff McAdams | 10:22 AM | 7-17-2008

Is there a page that has visuals for people who are not high-end techies but could post things in their blogs? I want to put this in my station newsletter - but there are so many words and not so many pictures.

Sent by Ann V. | 10:48 AM | 7-17-2008

vary sweet. notice you allow access to streaming mp3s (.m3u), something not yet even on NPR's own story pages:
http://hearingvoices.com/news/2008/07/npr-api/

Sent by Barrett Golding | 12:21 PM | 7-17-2008

There were quite a few questions that we addressed when developing the API

Such as ... ?

As a developer (and one whose job is asking for an API such as this), I would be interested to hear what technologies you explored (including ones you threw away and why), what design decisions you made (and why), what hurdles you encountered (and how you overcame them), etc.

While the eventual technologies you incorporate are important, I think it would be very illuminating to explain how you approached the underlying design.

P.S. Having a preview button would be a good addition to the comments page.

Sent by John L. | 12:33 PM | 7-17-2008

Ann V,

The Query Generator makes it easy to add content to a web page without a lot of technical voodoo. To use it:

1. Go to the query generator page (http://www.npr.org/api/queryGenerator.php) and select the types of stories you are interested in. Stories are organized by Topic, Programs, Bios (the author of the story), and so on.

2. Go to the Fields tab and select Javascript Widget as the output format.

3. Hit the Create API Call button. You will see a URL appear in the box above the button. Save this URL for the next step.

4. Add the following snippet of code to your web page, substituting the URL you saved in the previous step:

<script type="text/javascript" src="PASTE_YOUR_URL_HERE"></script>

For example, I selected Election 2008 from the Topics tab, and Nina Totenberg from the Bios tab. After doing the steps above, I end up with:

<script type="text/javascript" src="http://api.npr.org/query?id=1102,2101289&output=JS &apiKey=MDAwMDk5MDAxMDEyMTQ1MDM5OTkxMDlhNA001"></script>

If you want to preview what this will look like on your web page, you can set the output to HTML Widget on the Fields Tab, click Create API Call, and then click Run API Call.

One more thing: by default, this will return only stories that match all the selections you make on the tabs. So if you select Economy, Poetry, and Health Care on the Topics tab, you'll probably find that no story belongs to all three of those topics. If you want to get stories that belong to any of those topics individually, go to the Control tab and select "Or" in the Boolean for IDs box.

Sent by Harold Neal | 2:00 PM | 7-17-2008

John L.,
Your question about the technology decisions is a good one and we will be posting some more details about this (in a separate blog post) soon.

Sent by Daniel Jacobson | 2:23 PM | 7-17-2008

Maybe I'm missing something. No Fresh Air?

Sent by patfla | 3:06 PM | 7-17-2008

@patfla: Please see our post on the API and rights issues. We're launching the beta version of the API for shows that we have full rights to redistribute. Unfortunately, Fresh Air isn't one of those shows, as we don't produce it ourselves. We do hope to add more shows over time as these rights issues are worked out.

Sent by andy carvin, npr | 3:23 PM | 7-17-2008

Thanx. And yes, just discovered that on techcrunch.com

Still, the mind boggles at what is available. Now.

Sent by patfla | 3:30 PM | 7-17-2008

Congratulations, NPR Digital Media. This API is a great asset for the public and a valuable step forward for NPR. Hooray!

Sent by Maria Thomas | 10:42 AM | 7-18-2008

Brillant in concept and a design even us low techies can navigate. Your mothers must be proud! Kudos NPR Digital Media! D. Selig

Sent by Donna Selig | 4:58 PM | 7-18-2008

Schweet! I can't wait to play with this.

Sent by melody kramer, npr | 2:21 PM | 7-21-2008

Love the query generator, it is very slick. I also like that you allow for RSS and mediaRSS but it is unfortunate that the enclosure tag is missing from these formats which prevents it from being used in a podcatcher like iTunes. Granted this could be a tough thing to do generically if a story has lots of different audio samples but for the most part, the default of adding the primary audio artifact in MP3 format as the enclosure tag seems like the right thing to do. That's what I intend to do in a little program that I am writing to "fix" your feeds.

Sent by Mark Mascolino | 11:55 AM | 7-28-2008

Inside NPR.org