MapQuest Platform Web Services

Welcome to the MapQuest Platform Web Services. The Platform Web Services provide an easy HTTP interface to MapQuest functionality.

Currently Available Services

URL Construction

MapQuest Platform Web Service URLs have the following components:

hostname ()
service name (e.g. 'directions' for the Routing service)
version number (e.g. 'v1')
routing method (e.g. 'route' for the Routing service)

When you combine all four parts, you will have a base URL such as:

/directions/v1/route

The base URL will then be followed by other query parameters in the form of key/value pairs. Multiple request parameters are separated by an ampersand (&). Please note that these key/value pairs must be properly URL-encoded. The following table describes the parameters common to all MapQuest Platform Web Services:

Request Parmameter	Description	Accepted Request Data	Required?
key	The key you received when you registered for service. If you have not registered for service, you will need to do so at the MapQuest Developer Network site. NOTE: This key is slightly different than the one used for the 5.0 to 5.3 JS and AS3 SDKs. If you have a pre-existing key that does not seem to work, Please check the My Account page at the MapQuest Developer Network to verify you are using the correct key.	[A valid key string]	Yes
format	Specifies the default format for input and output. The `"inFormat"` and `"outFormat"` parameters, if supplied, override this parameter.	Must be one of the following, if supplied: json xml	No (Defaults to `"json"` when using POST; otherwise it determines which to use based on parameters given)
inFormat	Specifies the format of the request. If this parameter is not supplied, the input format is assumed to be JSON-formatted text. The JSON-formatted input text must be supplied as either the `"json"` parameter of an HTTP GET, or as the BODY of an HTTP POST. If this parameter is `"xml"`, the XML-formatted input text must be supplied as either the `"xml"` parameter of an HTTP GET, or as the BODY of an HTTP POST.	[See individual service for supported formats]	No
outFormat	Specifies the output format of the response	[See individual service for supported formats]	No
callback	A JavaScript function name. The JSON-formatted response will be wrapped in a call to the supplied callback function name to provide JSONP functionality. This functionality might be needed to do cross-site scripting. See the Wikipedia.org entry for JSON for more details.	A valid JavaScript function name, if supplied.	No

The simplest request is a Route request that sends JSON text in the BODY of an HTTP POST, and returns JSON text in the HTTP response:

/directions/v1/route?key=[YOUR_KEY_HERE]

HTTP GET URL:

If you send your request via an HTTP GET, you will need to provide all appropriate parameters as query parameters.

See the individual service documentation for a full list of accepted query parameters.

Example Route request via HTTP GET:

/directions/v1/route?key=[YOUR_KEY_HERE]&from=Lancaster,PA&to=York,PA

HTTP POST URL:

If you send your request via an HTTP POST, you will need to send a request body which contains text in the format determined by the "format" or "inFormat" parameters described above. If the "inFormat" request parameter is not supplied, the request body is assumed to be a JSON-formatted Route Request.

Note: You must set the "Content-Type" header as appropriate for the content of your POST:

Input Format	Content-Type
JSON	application/json
XML	text/xml

Example Route request via HTTP POST and JSON:

POST URL: /directions/v1/route?key=[YOUR_KEY_HERE] POST BODY: { locations:[ "State College, PA", "Lancaster, PA" ] }

You could implement the same example with an HTTP GET request by including the "json=..." request parameter:

/directions/v1/route?key=[YOUR_KEY_HERE]&json={locations:["State College,PA","Lancaster,PA"]}

Example Route request via HTTP POST and XML:

POST URL: /directions/v1/route?key=[YOUR_KEY_HERE]&format=xml POST BODY: <route> <locations> <location> State College, PA </location> <location> Lancaster, PA </location> </locations> </route>

You could implement the same example with an HTTP GET request by including the "xml=..." request parameter:

/directions/v1/route?key=[YOUR_KEY_HERE]&format=xml&xml=<route><locations><location>State College,PA</location><location>Lancaster,PA</location></locations></route>

Mixing JSON/XML formats and key/value pairs:

Requests that use key/value input for specifying parameters to the service, must only specify key/value parameters to the service. When using the key/value pairs for parameters, the service will ignore any "json=", "xml=", or POST data of either of those formats. The folowing example demonstrates a failure condition for batch geocoding.

POST URL: /geocoding/v1/batch?key=[YOUR_KEY_HERE]&format=xml&maxResults=10 POST BODY: <batch> <locations> <location> State College, PA </location> <location> Lancaster, PA </location> </locations> </batch>

In the above example the geocoding service sees a "maxResults=10" on the URL,then assumes the request is specifying locations as key/value pairs, "location=loc1&location=loc2...". Since none of these "location=" fields exist on the URL, the geocoding service assumes no locations are specified.