AT&T is a proud supporter of NPR

 
 

 

Get started!
Login | Register

 

API Output Reference

Below is the reference for the API's output. This document is primarily focused on NPRML, although other output formats are discussed as well.

Document Structure for NPRML
 

The basic document structure of the NPRML output is

 
Data Elements
 

There are three levels of fields returned in an NPRML document: messages, meta information for the query, and the story-level elements. To see the messaging details, go to API Messaging Reference. The definitions for the meta information and story-level elements can be found below.

Meta Information for the Query
The Meta Information is returned with every NPRML result set.

FIELD NAME FIELD DESCRIPTION SUB-ELEMENTS AND PARAMETERS
title The title of the requested query. If the query has multiple IDs, the title will reflect the titles of all of the requested IDs. No parameters
teaser A brief description of the requested query. If the query has multiple IDs, the description will reflect the descriptions of all of the requested IDs. No parameters
miniTeaser A shorter description of the requested query. If the query has multiple IDs, the description will reflect the descriptions of all of the requested IDs. No parameters



Story-Level Elements
For each Story-Level Element below, they can be requested by adding the field name to the "fields" parameter in the query string.

FIELD NAME FIELD DESCRIPTION SUB-ELEMENTS AND PARAMETERS
story The parent node for each story returned by the query. id : The unique ID for the story returned. This parameter is always returned whenever a story is returned.
link Link to story on the NPR.org website. This element could also be the link the story via the API. type : Determines the nature of the link. Current type values are "html", which points to NPR.org, and "api", which points to this API.
title The title of the returned story. This is the main title or headline. No parameters
subtitle A short, sentence-like description of the returned story. No parameters
shortTitle An abbreviated title for the returned story, not to exceed 30 characters. No parameters
teaser The main abstract for the returned story, describing what the story is about. No parameters
miniTeaser An abbreviated abstract for the returned story, describing what the story is about. No parameters
slug The main association for the returned story, whether it is to a topic, series, column or some other list in the system. No parameters
thumbnail The image URL for a small representative image for the returned story. This image is designed to entice readers to view the story. No parameters at this level. thumbnail does contain sub-elements called "medium" and "large".
thumbnail.medium The URL to the image file. No parameters
toenail The image URL for an even smaller representative image for the returned story. This image is designed to entice readers to view the story. No parameters at this level. toenail does contain a sub-element called "medium".
toenail.medium The URL to the image file. No parameters
storyDate The primary date/time associated with the publication of the returned story to NPR.org. No parameters
pubDate The date/the returned time the story was initially published to NPR.org, or the last date a significant update was published to NPR.org. No parameters
lastModifiedDate The date/time the returned story was last modified in any capacity to NPR.org. No parameters
keywords A comma-delimited list of key terms describing the returned story. This field is seldom used for NPR.org. No parameters
priorityKeywords A comma-delimited list of key terms that are very closely tied to the returned story. No parameters
organization The owner organization of the returned story. orgId : The unique ID of the organization for the returned story.
orgAbbr : The organization's abbreviation.
organization does contain sub-elements called "name" and "website".
organization.name The full name of the owner organization for the returned story. No parameters
organization.website Website associated with the owner organization for the returned story. type : Indicates the type of website provided by the owner organization (eg. "Home Page").
audio All available audio associated with the returned story. This will include all formats to which NPR has the rights to distribute. id : The unique ID for the audio asset.
primary : Defines whether or not the audio asset is the primary audio for the story.
audio does contain sub-elements called "duration" and "format". format also contains sub-elements.
audio.duration The duration of the audio asset. All formats for the audio will have the same duration. No parameters
audio.format Wrapper element for the various audio formats. No parameters at this level. format does contain sub-elements called "mp3", "rm" and "wm".
audio.format.mp3 The URL for the audio assets, in an MP3 format, that are available for the returned story. rights : Defines the delivery method for the MP3 files.
audio.format.rm The URL for the audio assets, in the Real Audio format, that are available for the returned story. No parameters
audio.format.wm The URL for the audio assets, in the Windows Media format, that are available for the returned story. No parameters
image All images associated with the returned story. id : The unique ID for the image asset.
type : TBD.
width : The width of the image in pixels.
src : The source URL for the image.
addBorder : Indicates if the image has a border in the asset itself.
image does contain sub-elements called "caption", "link", "producer", "provider" and "copyright".
image.caption The caption for the image, describing the contents of the image and/or the image's relationship to the returned story. No parameters
image.link The URL to which the image should link. url : The URL to which the image should link.
image.producer The actual producer of the image, to whom the image will get credited. No parameters
image.provider The owner or provider of the image, which may be independent from the image producer. url : The URL of the provider. This is used for attribution purposes and must convey with the image.
image.copyright The copyright information (year) for the image. No parameters
relatedLink Links to related stories, both on NPR.org and elsewhere. id : The unique ID for the link - only returned if the link type is "internal".
type : Indicates the type of link. Current possible types are "internal" and "external".
relatedLink does contain sub-elements called "caption" and "link".
relatedLink.caption The link text for the related link. No parameters
relatedLink.link The actual URL for the related link. type : Determines the nature of the link. Current type values are "html", which points to NPR.org, and "api", which points to this API.
pullQuote Quotes from the returned story that have been identified as particularly compelling by NPR editorial staff. No parameters at this level. pullQuote does contain sub-elements called "person" and "date".
pullQuote.person The person or people responsible for the quote. No parameters
pullQuote.date The date of the quote. This can be anything from a specific moment in time to a year. No parameters
text The full text of the returned story without any markup, broken out by paragraph. No parameters at this level. text does contain a sub-element called "paragraph".
text.paragraph The text elements are broken up at the paragraph level. num : The num parameter indicates the order of the paragraphs relative to each other under their corresponding text element.
textWithHtml The full text of the returned story, complete with markup, broken out by paragraph. No parameters at this level. textWithHtml does contain a sub-element called "paragraph".
textWithHtml.paragraph textWithHtml elements are broken up at the paragraph level. num : The num parameter indicates the order of the paragraphs relative to each other under their corresponding textWithHtml element.
listText A supplemental text field used for a variety of reasons. listText could be a ordered or unordered list of interesting points, a timeline, an additional highlighted paragraph related to the story, or possibly even an extension of the text (and textWithHtml) fields. tag : The tag parameter defines the intention of the editor in grouping the related items of the listText. Possible values include "p".
listText does contain a sub-element called "item"
listText.item listText elements are broken up at the item level. num : The num parameter indicates the order of the items relative to each other under their corresponding listText element.

 

Formats
 

NPRML example (*click to view)


RSS example (*click to view)


mediaRSS example (*click to view)


ATOM example (*click to view)


JSON example (*click to view)


HTML Widget (*click to view)


Javascript Widget (*click to view)


 
Resources Relevant to this API
 

Definitions and Technical Specifications
API Definition: http://en.wikipedia.org/wiki/API
NPR's RSS Help Page: http://www.npr.org/help/rss.html
RSS Technical Specification: http://cyber.law.harvard.edu/rss/rss.html
iTunes' Podcast Technical Specification: http://www.apple.com/itunes/store/podcaststechspecs.html
MediaRSS Technical Specification: http://search.yahoo.com/mrss
Atom Technical Specification: http://www.atomenabled.org
JSON Technical Specification: http://www.json.org

Validation Engines
RSS, MediaRSS and Atom Validation: http://www.feedvalidator.org