Before you begin using the NPR Story API, you might be wondering what an API is and how it works. We've put together a handy guide to provide you with some of the more basic concepts of an API and we'll share the reasons as to why it's an important tool for your station and npr.org.
Click and skip to a specific topic or start reading below.
What is an API?
API stands for Application Programming Interface.
But what does that mean?
Put simply, an API is an interface that applications can use to share data. Instead of directly sharing data from the application's source, an API is used as a safe go-between. An API isn't a program on its own, rather it's coding within an application that runs in the background.
Example: Think of an API as a side door that allows you to retrieve data from a guarded room. Once you’ve gained access, you’re able to share data with the owner of the API and use their data to suit your needs.
Many popular web applications provide a portion of their data using APIs. Sites like Google Maps allow the public to use their collection of map information using an API and Twitter distributes user and tweet data via their Twitter API.
A major goal for Twitter and Google is to give people access to this data so that they can then integrate and present it using custom applications.
Why did we create an NPR API?
Distributing NPR content (a.k.a NPR data) throughout a vast network of stations, websites and apps is one of NPR’s most important duties. Using an API helps NPR achieve this goal. Instead of allowing people directly into NPR databases, an API provides us with a controlled point of access from which we can release data.
The API promotes NPR’s distribution goals in the following ways:
- NPR can distribute content to our member stations using the API.
- Stations can use the NPR API to share content data with npr.org, other stations and the public.
- By using an API, NPR allows the public to access our content and gives them the freedom to create new ways to mix, match and display it (known as “mashups”). For example of a mashup, checkout NPRBackstory which uses the NPR API on Twitter.
- Finally, the API "future proofs" our content and ensures it can be shared on various platforms and emerging channels where we’ve seen growth, such as mobile.
What’s inside the NPR API?
Though we call it the "NPR API," several different APIs are housed under this one term. This suite of APIs can access information related to content, stations, transcripts, podcasts and our staff.
It’s also common within NPR that people say “The API” when referring to one of our suite’s APIs called the NPR Story API. The NPR Story API is our most popular API and the one that stations should focus on. It’s the API which stations can retrieve (or pull) npr.org content from and ingest (or push) their content into.
What is the NPR Story API made of?
The NPR Story API holds stories, photos, audio and other data associated with npr.org and member station content. This includes NPR programs dating back to 1995 as well as text, images and other web-only content. The archive consists of well over 250,000 stories that are grouped into more than 5,000 different aggregations.
Once content is pushed inside the NPR Story API it’s mainly distributed in 3 ways:
- Create Once, Publish Everywhere (COPE) - Stations and npr.org push content into the API and then pull the content onto other platforms, such as other station-owned websites and mobile apps.
- Station Networks - Content is shared between multiple stations in a content network, both on web sites and mobile apps.
- National - Station content is featured on npr.org and NPR mobile apps with links back to station digital properties.
In order to access the Story API, and other NPR APIs, the requesting party must have what is called an API “key.”
What is an API key?
API owners can code their API to only allow access if the request comes with an API key. This is how the NPR Story API works. Anyone who wants access to NPR API content must have a key first.
With this key the API recognizes not only whom the request is coming from but also what that person is allowed to see. For example, NPR grants limited access to public keys whereas a station's key is allowed to access more.
Where do you get an API Key?
Public NPR API keys are made available by registering for an account on npr.org. A station should request an API key by contacting Digital Services (if they don’t have one already).
API Key Permissions
Once you obtain an API key you can use it to query (i.e. browse) the NPR APIs in a variety of ways, which you can learn more about here. Again, when you query the API it will only return what your key is allowed to access so if you're not getting certain content it's possible your key isn't allowed to see it.
How do stations connect with the NPR Story API?
When working with a Core Publisher CMS, many of fields you use to enter in content also represent fields for elements that are automatically synced up to ingest into the NPR Story API. These elements, such as the author, title, image, audio and article text, are considered metadata. Stations not using Core Publisher would need to have their in-house developers modify their CMS so that it interacts with the API. For help, please contact Digital Services.