NPR Tech Center

The following is a definition of the various list types available in the API along with the URLs to access the XML for these lists. Topics
Collection of NPR stories that represent a given topic or subject matter. (eg. Health Care, Interviews)
All Topics : http://api.npr.org/list?id=3002
All Topics and Music Genres : http://api.npr.org/list?id=3218

Music Genres
Collection of NPR stories that represent a given musical genre. (eg. Rock/Pop/Folk, Jazz)
All Music Genres : http://api.npr.org/list?id=3018
All Topics and Music Genres : http://api.npr.org/list?id=3218

Programs
Collection of NPR stories that aired on an NPR program. (eg. All Things Considered, Tell Me More)
All Programs : http://api.npr.org/list?id=3004

Bios
Collection of NPR stories as reported by an NPR personality. Personalities are sorted by letter. (eg. Nina Totenburg, Steve Inskeep)
All Personalities: http://api.npr.org/list?id=3007

Music Artists
Collection of stories that are about music artists. Artists are sorted by letter. (eg. Bob Dylan, Death Cab For Cutie)
All Recently Featured Music Artists : http://api.npr.org/list?id=3008
All Music Artists : http://api.npr.org/list?id=3009

Columns
Collection of stories containing opinions and perspectives of an NPR personality. (eg. Watching Washington, Song of the Day)
All Columns : http://api.npr.org/list?id=3003

Series
An ongoing collection of NPR stories on a topic. (eg. Climate Connections, Summer Books)
All Recent Series : http://api.npr.org/list?id=3006

Blogs
Collection of posts on a theme. (eg. Inside NPR.org, All Tech Considered)
All Blogs : http://api.npr.org/list?id=3013

Categories
A short description for a blog. (eg. Editorial, API, or Audience Estimates for the blog Inside NPR.org). Requires a blog ID, found via All Blogs, above.
All Categories for Inside NPR.org : http://api.npr.org/list?typeId=3132&id=91000411

Tags
A short description for a blog post. (eg. actors, approval rating, feedback, zombies)
All Tags : http://api.npr.org/list?id=3024

List parameters tell the List API which items to return and how to return them. There are two types of parameters (Data Parameters and Output Parameters). Each of the parameters is described below:

Data Parameters

NAME	DESCRIPTION
storyCountAll	Returns only items with at least this number of associated stories. This parameter is available for all lists.
storyCountMonth	Returns only items with at least this number of associated stories published in the last month. This parameter is available for all lists.
storyCountToday	Returns only items with at least this number of associated stories published today. This parameter is available for all lists.
childrenOf	Returns only items which are assigned to the given topic ID. For example, ?id=3006&childrenOf=1008 would return only recent series which are assigned to "Arts & Life". This parameter is available for the lists All Topics and Recent Series
hideChildren	If set to "1", returns only topics which are not subtopics of another topic. For example, ?id=3002&hideChildren=1. This parameter is only available for the All Topics list.

Output Parameters

NAME	DESCRIPTION
output	If the output parameter is specified for a list, it currently has only one possible value: JSON. If it is not specified, the output will be list XML. This parameter is available for all lists.
output.JSON	Setting output to JSON will return list results in a JSON format. To learn more about JSON, see the JSON Specification.
callback	This parameter is only used with JSON output. If callback is not specified, JSON output contains the JSON-object representing the results. If callback is specified, then the JSON-object is wrapped in a callback function that is named with the value of this parameter. This allows the user to define how the response is handled in their code and works-around the same-domain origination policy of Javascript. This parameter is available for all lists.

The input parameters tell the API what stories to return and how to return them. There are four types of parameters (Access Parameters, Data Parameters, Output Parameters and Control Parameters). Each of the parameters from the four types is described below:

Access Parameters

NAME	DESCRIPTION
apiKey	The apiKey parameter is required for all API requests. To get a key, you must register. Once registered, you can get and/or change your apiKey from your Account Manager. Upon registration, your apiKey will be saved to a cookie that will enable the Query Generator to apply your apiKey to your queries..

Data Parameters

NAME	DESCRIPTION
id	Returns stories that belong to the provided IDs. Lists of IDs must be comma-delimited (eg. 1001,2). At least one ID is required for all queries, unless the query is using searchTerm. See action on how multiple IDs can be handled.
date	Returns stories with the exact date requested. The special value date=current is also allowed. If one of the id parameters is a program, this will return stories from the last complete episode of that program. If none of the id parameters belong to a program, then date=current will return stories from today. Cannot be used with startDate or endDate
startDate	Returns stories with a story date later than or equal to the startDate. Can be used with endDate to return stories within a date range; dateType can modify the meaning of this parameter
endDate	Returns stories with a story date earlier than or equal to the endDate. Can be used with startDate to return stories within a date range; dateType can modify the meaning of this parameter
orgId	Returns stories that are provided by the selected organization. Owner organizations primarily include NPR and NPR member stations.
searchTerm	Returns stories that are considered matches to the searchTerm based on NPR's search engine. Can be used with searchType to inform the search engine which fields it should search.
searchType	Used with searchTerm to inform the search engine which fields it should search. Default is to search the full content of the story (full text, transcripts, etc). For a more targeted search, use searchTerm=mainText, which tells the search engine to search the only title and teaser fields for the story. Must be used with searchTerm.

Output Parameters

NAME	DESCRIPTION
meta	Controls the meta information for the API call. The meta information is described in greater detail in the Meta Information section of the Output Reference. The meta parameter can receive "none", "inherit" or "default". None will suppress the meta information completely. Inherit will mirror, to the extent possible, the fields requested by the fields parameter. Default, which is the same as not passing in the meta parameter at all, will return the title, teaser and miniTeaser for the API call.
output	The output parameter tells the API what the desired output format should be for the results. The default format is NPRML, but other formats including RSS, MediaRSS, Atom and JSON can be requested. For more details on the various output formats, go to the Output Reference. The API allows users to select RSS, for example, while extending the namespace to include fields beyond the standard RSS fields. Those extended namespace fields will be outputted in NPRML.
output.NPRML	NPRML is the default output structure for the document. To learn more about NPRML, see our Output Reference and Message Reference.
output.RSS	Setting output to RSS will return the results in the standard RSS 2.0 format. To learn more about RSS, see the RSS 2.0 Specification.
output.MediaRSS	Setting output to MediaRSS will return the results in standard RSS 2.0 format with the MediaRSS extensions. The RSS will be extended for audio and image assets. Currently, video is not supported by the API. To learn more about MediaRSS, see the Media RSS Specification.
output.Podcast	Setting output to Podcastwill return the results in standard RSS 2.0 format with the Podcast extensions, including an MP3 audio enclosure. For audio that NPR does not have the rights to offer as downloadable audio, these stories will be automatically suppressed from the output.
output.ATOM	Setting output to ATOM will return the results in standard Atom format. To learn more about Atom, go to Atom Enabled.
output.JSON	Setting output to JSON will return NPRML results in a JSON format. To learn more about JSON, see the JSON Specification.
output.HTML	Setting output to HTML will return the results in a limited HTML formatted block. The limitations are in the content as its fields are not configurable and we will only return title, date, teaser, the link to the story, and links to the MP3, Real Audio and Windows Media audio (to the extent that they are available).
output.JS	Setting output to JS will return the results in a limited HTML formatted block that has been wrapped around a JavaScript document.write statement. The limitations are in the content as its fields are not configurable and we will only return title, date, teaser, the link to the story, and links to the MP3, Real Audio and Windows Media audio (to the extent that they are available).
fields	The fields parameter tells the API which fields to return in the output for the results. For NPRML, you can pick and choose any combination of fields. For other formats, the standard fields for that format will be returned, although you can extend the namespace beyond the standard by selecting other fields. To see a complete list of possible fields, go to the Query Generator and click on the Fields tab.
fields.title	Includes the title of the story. A title exists for all stories.
fields.teaser	Includes the teaser of the story. A teaser exists for all stories.
fields.storyDate	Includes the date of the story. A date exists for all stories.
fields.show	Includes all program associations of the story. Not all stories are associated with a program.
fields.byline	Includes all credited contributors of the story. Not all stories have credited contributors.
fields.text	Includes the full text of the story. This field contains no markup in it - it is just the pure text. Not all stories have full text.
fields.audio	Includes all audio assets of the story (to the extent that we can distributed them). Not all stories have audio assets, although the vast majority of stories do.
fields.image	Includes all image assets of the story (to the extent that we can distributed them). Not all stories have image assets.
fields.textWithHtml	Includes the full text of the story. This field contains all of the editorially applied HTML to add styles to the content (such as bolding text, URLs embedded in the text, etc.). Not all stories have full text.
fields.listText	Includes any lists or text extensions of the story. This fields is used in a variety of ways and is used to enrich the story by providing timelines, story summaries, extended information about the story, etc. Not all stories have list text.
fields.pullQuote	Includes any isolated quotes of the story. Not all stories have pull quotes.
fields.parent	Includes all relationships between the story and any list to which it belongs. Not all stories have parents.
fields.relatedLink	Includes all relationships of the story to other stories on NPR.org or to web pages on other sites. Not all stories have related links.
fields.album	Includes all albums associated with the story. Not all stories have album associations.
fields.artist	Includes all musical artists associated with the story. Not all stories have artist associations.
fields.product	Includes all purchasable products associated with the story. Not all stories have product associations.
fields.transcript	Includes a link to the transcript API, if a transcript is available for this story.
fields.correction	Includes information about any correction to the story, such as (possibly empty) title, text, and date.
fields.all	All is the default setting for NPRML if the fields parameter is not explicitly used. All returns every field that is available for the story.
fields.none	Excludes all content fields and will only return the id and links associated with any results.
fields.summary	Shorthand for an aggregation of specific fields, including title, subtitle, shortTitle, teaser, miniTeaser, slug, thumbnail, toenail, storyDate, pubDate, lastModifiedDate, keywords, and priorityKeywords. Some of these parameters can only be seen using the summary or all options in the fields parameter.
fields.titles	Returns all titles, including title, subtitle, shortTitle, and slug.
fields.teasers	Returns all teasers, including teaser and miniTeaser.
fields.dates	Returns all dates, including storyDate, pubDate, and lastModifiedDate.
callback	This parameter is only used with JSON output. If callback is not specified, JSON output contains the JSON-object representing the results. If callback is specified, then the JSON-object is wrapped in a callback function that is named with the value of this parameter. This allows the user to define how the response is handled in their code and works-around the same-domain origination policy of Javascript.

Control Parameters

NAME	DESCRIPTION
sort	Determines the order in which the stories will be returned. Options include date descending, date ascending, editor assigned, and featured. Editor assigned is the order that NPR editors have chosen. Featured will put the featured stories for a show at the top of the result list; it is only useful if a program ID is included in the list of ID parameters in the query. Default sort order is date descending.
startNum	Used for pagination of results, startNum tells the API where in the result set to start returning stories. If not used with numResults, the API will return up to 20 stories. If numResults is specified, the API will return the specified number of results. This allows for requests of stories 1-20, 21-40, 41-60, etc.
numResults	Restricts the number of stories returned by the API. The maximum number of stories return is currently 20. If numResults is a number greater than the maximum, the API will return the maximum. Can be used with startNum to paginate through results. This allows for requests of stories 1-20, 21-40, 41-60, etc.
action	Informs the API how to treat a list of IDs passed in through the id parameter. Using "or" means that stories that appear in any of the IDs will be returned. Using "and", or omission of the action parameter, means that only stories that appear in all of the IDs will be returned. Using "union" will return results as though from a separate query for each ID. For example, id=10001,10003&action=union&numResults=3 would return up to six stories, since it's the sum of both id=10001&numResults=3 and id=10003&numResults=3.
requiredAssets	Limits the result set to contain only stories with a particular type of asset. Allowed values are "audio", "image", "text", and "correction". You can specify more than one required asset by separating the values with commas. For example, requiredAssets=image,audio,text,correction would return only stories that contain images and audio and text and which have been corrected after publication.
dateType	Controls the meaning of startDate and endDate.
dateType.story	Date parameters refer to the story date. This is the default.
dateType.correction	Date parameters refer to the correction date. (Implies requiredAssets.correction)

Other Parameters

NAME	DESCRIPTION
title	Changes the title of the feed at the list level. This parameter is optional. If this parameter is not used, the system will provide the default title for the requested feed.

Each call is made to the API via an HTTP REQUEST. This url should contain the stem and appended parameters and values.
The stem of the url is http://api.npr.org/query?. Parameters should follow the question mark.

Example:
http://api.npr.org/query?id=1007,3&numResults=10

For full functionality, it is suggested that users return the NPR's custom XML structure, called NPRML.

• This functionality includes messaging and error handling to explain results.
• This return will include full meta-data definitions for NPR stories.
• This format can be amended to return a simple list of user-defined elements or pre-defined aggregations.

In addition to NPRML, the API can return the following formats: RSS, MediaRSS, ATOM, and JSON, as well as HTML and JavaScript widgets.

For any of the standardized return formats, fields can be returned to extend their namespaces. The extra fields will be returned in an NPRML format.