Using the msnbc.com APIs

Welcome to the msnbc.com APIs. With these APIs, you can access thousands of stories, images, videos, and more published on msnbc.com.

The msnbc.com APIs expose three "types", each of which has an associated API URL. The three types are:

• Documents
The Document type represents articles, videos, images, slide shows, and other content you view on msnbc.com. The Documents API returns Documents related to a list of Entities (keywords), another Document, or a geographic location.
• Entities
Entities are statistically-significant keywords associated Documents. The Entities API returns Entities associated with Documents and Topics.
• Topics
Topics pages are special msnbc.com pages that are created for entities that reach a specific threshold of "importance". This API returns Topics pages related to Entities or Documents.

Each of these APIs can be accessed via http://api.msnbc.msn.com/<api_name>, and is described in more detail in the sections that follow.

Documents

The Documents API has 3 methods:

• GetDocuments (http://api.msnbc.msn.com/documents/getdocuments)
Returns Documents based on a list of entities or a document ID. By passing in a list of entities, you get the documents most related to that list. If you pass in a document ID, you get the documents most related to that document.
• GetDocumentsByGeography (http://api.msnbc.msn.com/documents/getdocumentsbygeography)
Returns Documents based on a geographic location. The geographic location can be specified by a latitude/longitude pair, a postal code, a bounding box, or a Document ID.
• GetDocumentDetails (http://api.msnbc.msn.com/documents/getdocumentdetails)
Returns the Document object for each of the documents you specify in the documentList parameter.

See the table of parameters for more information on the parameters you can use with these methods.

Entities

The Entities API has 1 method:

• GetEntities (http://api.msnbc.msn.com/entities/getentities)
If you specify the docid parameter, this method returns the list of entities associated with that document. If you provide a list of entities with the entities parameter, this method returns entities related to the provided entities. If you specify the keyword parameter, this method returns a list of entities that match the keyword. Otherwise, this method returns the top entities for the specified date range.

See the table of parameters for more information on the parameters you can use with these methods.

Topics

The Topics API has 1 method:

• GetTopics (http://api.msnbc.msn.com/topics/gettopics)
Returns topics related to the document ID you specify with the docid parameter, or to an entity you specify in the entities parameter. Note: you can only pass in one entity in the entities parameter when using this method.

See the table of parameters for more information on the parameters you can use with these methods.

Parameters

Parameter	Description	Supported Methods
entities	Specify one or more entities, separated by semi-colons. Precede an entity with a minus (-) to indicate a NOT. Use a trailing asterisk (*) for wildcard matching of 3 or more characters.	GetDocuments, GetEntities
docid	Specify a valid ID for a Document object. The Document ID is returned in all GetDocuments and GetDocumentsByGeography calls, and is also found in the URL for msnbc.com stories.	GetDocuments, GetDocumentsByGeography, GetEntities
documentList	Specify one or more Document IDs, enclosed in curly braces {} and separated by commas. For example, documentList={123450,136798} returns Document objects for two documents. The Document ID is returned in all GetDocuments and GetDocumentsByGeography calls, and is also found in the URL for msnbc.com stories.	GetDocumentDetails
keyword	Specify a keyword (or part of a word or phrase) to get a list of entities that match.	GetEntities
startDate	Specify the first day of the date range. The default is today - 31 days.	All
endDate	Specify the last day of the date range. The default is today.	All
contentType	Specify the content type(s) of the Document, using the first two letters of the type: article video image For multiple content types, separate values with a comma (,). For example, contentType=ar,vi returns both articles and videos.	GetDocuments, GetDocumentsByGepgraphy
siteId	Specify the news source, where: 1 = msnbc.com 2 = CNBC 3 = NBC Sports	All
maxResults	Specify the maximum number of types (Documents, Entities, or Topics) to return. The default is 50, and the maximum is 1000.	All
output	Specify the output data format. If output is not specified, JSON is returned. If output is specified and is not one of the valid types, plain old XML (POX) is returned. Valid output types for Document types are: XML, ATOM, RSS, KML, and GeoRSS. For Topics and Entities, only JSON and XML are supported.	All
jsonp	If output is not specified, and the jsonp parameter is, then the data is returned as jsonp (i.e., wrapped in the method name you specify).	All
centerPoint	Specify a latitude/longitude pair for the geographic location around which Documents occur. The format is: centerPoint={latitude:47.123;longitude:-122.012}	GetDocumentsByGeography
postalCode	Specify the postal code (ZIP Code) of the location for Documents. Note: the API does not just return documents that occur within the postal code you specify; like centerPoint, this parameter is used in conjunction with the radius parameter to define a circle. The center of the circle is the geographic center of the postal code polygon you specify.	GetDocumentsByGeography
radius	Used in conjunction with the centerPoint and postalCode parameters to define a circle. Specify the radius of the circle in miles.	GetDocumentsByGeography
bBox	The Bounding Box in which documents will be returned. Following the conventions set forth in the KML specifications for a Network Link, a bounding box is specified in the following format: bbox=west_longitude,south_latitude,east_longitude,north_latutude. For example, bbox=-125.5155787841414,45.56295967714189,-118.425088267849,49.20392845297751	GetDocumentsByGeography
sort	Specifies the sort order. Valid sort values are any of the Document object's properties, optionally followed by a space (%20) and either "asc" or "desc" to specify the sort direction. You can also specify sort=scatter, which returns results sorted by both date and geographic distance from the center of the "view" specified. Scatter is only used with GetDocumentsByGeography.	GetDocuments, GetDocumentsByGeography

Output Formats

The APIs return data in one of the following output formats:

Examples

Get Documents

GetDocumentsByGeography

GetEntities