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 2 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. If you specify a bounding box

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 provide a document ID, this method returns the list of entities associated with that document. If you provide a list of entities, this method returns entities related to the provided entities. Otherwise, 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.

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 Document's ID. The Document ID is returned in all GetDocuments and GetDocumentsByGeography calls, and is also found in the URL for msnbc.com stories.	GetDocuments, 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 of the Document, using the first two letters of the type: article video image	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 "date", "id", "distance", and "scatter". Using sort=scatter returns results sorted by both date and geographic distance from the center of the "view" specified. Currently only used with GetDocumentsByGeography; results from GetDocuments are sorted by descending date (newest content first).	GetDocumentsByGeography

Output Formats

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

Examples

Get Documents

GetDocumentsByGeography

GetEntities