API Input Reference
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.
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
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
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
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
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
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
An ongoing collection of NPR stories on a topic. (eg. Climate Connections, Summer Books)
All Recent Series : http://api.npr.org/list?id=3006
Collection of posts on a theme. (eg. Inside NPR.org, All Tech Considered)
All Blogs : http://api.npr.org/list?id=3013
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
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:
|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||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.|
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:
|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..
|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.|
|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).|
|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.|
|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)|
|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.
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.
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.