ruby-npr | A Ruby Wrapper for the NPR API

How do I get started?

sudo gem i rubynpr

Create a new NPR client by feeding it your NPR API key, available here. The api_key method can be used later to access the key, or it can be used to set the key if one isn't set as soon as a Client is created.

@client = NPR::Client.new(:api_key => 'your NPR api key')

Start telling stories!

With the NPR API, you can pull up content by getting at a story directly or via lists of related content. If you know the ID of a story, you can pull it up directly:

@results = @client.query(:id => 95965641)

This particular query will pull up Networks Police YouTube For Copyright Violations. They should just stop, but yeah, you get the point. lol. The query method takes several options, too, in order to refine results. Also, note that query will always require the :id option. If it's not included an InvalidQueryOptions exception will be raised!

Don't want every story NPR has on the economy (topic ID 1017) or anything else? Limit your results:

@econ_results = @client.query(:id => 1017, :num_results => 3)
@sept_results = @client.query(:id => 1017, :end_date => Time.utc(2008, 9, 30))

Above, @econ_results ends up being a list of all the stories returned on the economy (a StoryList more specifically) according to the parameters specified. In the first case, we'll get the three latest stories NPR has published on the economy. @sept_econ_results holds a StoryList with several stories on the economy up to and including those published on September 30th, 2008.

If you want to pull out a particular story to work with from previous results:

@econ_story = @client.results.list[1]

Later, you can access all the fields that comprise an NPR story:

@econ_story.title
> "'Dr. Doom' Calls U.S. Economy Worst Since WWII"
					
@econ_story.mini_teaser
> "Henry Kaufman says the way to protect the economy is to protect the..."

What about story content?

You can access the content of a Story using either the html_text or plain_text methods. html_text returns an array built from the paragraphs of the story complete with HTML. plain_text is just an array with the plain text paragraphs from the story.

@econ_story.html_text
@econ_story.plain_text

The rest of the fields that are available can be found in NPR's API docs or in the RDoc for ruby-npr.

What about topics?

NPR keeps a huge list of topics you can pull data from here. The list of all NPR topics is available with:

@topics = @client.list(:id => 3002)

This returns a huge list of topics all neatly packaged in a TopicList object. These topics are Item objects that you access like stories.

@some_topic = @topics.list[13]

A topic can used in queries, too, instead of using a string. It returns all stories associated with the given topic just the same!

@stories = @client.query(:id => @some_topic)

What if something goes wrong?

ruby-npr makes use of a few exceptions to indicate when something's amiss. InvalidAPIKey, DeactivatedAPIKey, NPRSystemIssues, InvalidList, and InvalidQueryOptions are exceptions handled in ruby-npr. Exceptional conditions from NPR are described here.

As well as exceptions, warnings are returned from NPR if, for example, a request is created that includes options that don't make sense together. As noted from NPR, these issues may not prevent NPR from returning results, but it could prevent areas of the request from getting handled. In this case, warnings packaged into Warning objects are accessible in the following way:

@client.warnings

Even if warnings are generated from a query, results may still be found in @client.results. The full list of warnings that can be generated are available here.

What else?

As far as ruby-npr goes, that's basically it! Enjoy!