Common Search Parameters

Over the multiple search functions, there are various parameters which are common for all of them.

Contents

Query Parameters

Certain parameters must be put into the query string of the request. Below is a table describing those parameters.

Name Description
key
String
A unique key to authorize use of the Search Service. If you do not know your key or do not have an account with us, visit the Mapquest Developer Network.

This is a required parameter!
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.

Must be one of the following, if supplied:
  • json
  • xml
Defaults to "json" if not supplied
json This parameter, if present, should contain the JSON-formatted text of the request. Use this parameter if you want to submit your request in JSON format, but do not want to use an HTTP POST to submit body text.

Note: Remember to URL-escape the text in this parameter!
xml This parameter, if present, should contain the XML-formatted text of the request. Use this parameter if you want to submit your request in XML format, but do not want to use an HTTP POST to submit body text.

Note: Remember to URL-escape the text in this parameter!
outFormat Specifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
  • kml - this output format will output a .kml file to download.
Defaults to "json" if not supplied
ambiguities
String 		Use this parameter to set the strategy for resolving ambiguous location names.

If this parameter is set to "ignore" , the Search Service will simply use the first location found for an address.

If this parameter is not set, or set to a value other than "ignore" , the Search Service will return a full list of the possible location matches in the collections attribute of the response.
mapDataList
List of MapData Objects		 MapData objects are map based data layers that can be searched. This is the data used to draw the map. With it you can search specific display types for specific information. Refer to the Map Data page for more information. Currently Map Data can't be searched with a Corridor Search (It's coming soon!).
hostedDataList
List of HostedData Objects		 HostedData objects will contain data hosted by Mapquest. This includes tables of points of interest from around the world, as well as allowing users to upload data to our servers for it to be stored. This parameter allows you to query these data sets as part of your search request. Refer to the Hosted Data page for more information.
remoteDataList
List of RemoteData Objects		 RemoteData objects contain data provided by the user as part of the request that will be included in the search. Refer to the Remote Data page for more information.

Options Parameters

There are also parameters which need to be placed inside an "options" object if using JSON or XML. If using key/value pairs, then use each parameter would just be another query parameter.

Name Description
units
String		 Specifies the type of units to use when calculating distance. Search results are then ordered by distance from lowest to highest. Notice there are some additional parameters here than in our other services. Acceptable values are:
  • m - Miles - Sorts the results by straight line distance in miles (straight line distance).
  • k - Kilometers - Sorts the results by straight line distance in kilometers (straight line distance).
  • wmin - Walking Minutes - Sorts the results by shortest walking time (calculated as an actual walking route).
  • dmin - Drive Minutes - Sorts the results by shortest driving time (calculated as an actual driving route).
  • dm - Drive Miles - Sorts the results by shortest driving distance in miles (calculated as an actual driving route).
  • dk - Drive Kilometers - Sorts the results by shortest driving distance in kilometers (calculated as an actual driving route).
Default value is "m"
maxMatches
Integer		 Maximum amount of results to return.
shapeFormat
String		 These shapeFormats are also described in more detail on the Geometry page. Shape format options:
  • raw - shape is represented as float pairs
  • cmp - shape is represented as a compressed path string with 5 digits of precision
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
  • simple - WKT standard for Simple Features.

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder.
See the Simple Features Wiki description page for more detail.
currentPage
Integer		 Set this to return a specific page of the results. Refer to the Paging Documentation for more details and samples on paging results.

Defaults to 1
pageSize
Integer		 Set value to limit the search results returned. Refer to the Paging Documentation for more details and samples on paging results.

Defaults to returning all results found.
pageKey
String		 This is the pageKey sent back with a previous request, it is used to retrieve the previous request's different pages of results.
kmlStyleUrl
String		 This is a URL to a .kml file that gives style attributes to different mapData results. There is a default file will be used anytime the output is KML, unless the kmlStyleUrl parameter is present. The file can be viewed here.

Common Response Parameters

Over the multiple search functions, there are various parameters in the response which are common for all types of searches.

Name Description JSON Example Return Value(s) XML Example Return Value(s)
info

This field contains information about the response.

The statuscode subfield is an integer return value. Refer to the status codes page for more details on our status codes and error messages.

The messages subfield is an array of error messages which describe the status 

info:{
   statuscode: 691,
   messages: [
      "Shape was not provided, please provide."
   ]
}

<info>
   <statuscode>
      691
   </statuscode>
   <messages>  
      Shape was not provided, 
	  please provide. 
   </messages>

</info>
ambiguities
Boolean		 This will return true or false if ambiguities could be returned. ambiguities: true <ambiguities>true</ambiguities>
units
String		 Specifies the type of units to use when calculating distance. Acceptable values are:
  • m - Miles
  • k - Kilometers
  • wmin - Walking Minutes
  • dmin - Drive Minutes
  • dm - Drive Miles
  • dk - Drive Drive Minutes
Default value is "m" 		units: m <units>m</units>
maxMatches
Integer		 Maximum amount of results to return. maxMatches: 5000 <maxMatches>5000</maxMatches>
shapeFormat
String		 Shape format of all shapePoints returned
  • raw - shape is represented as float pairs
  • cmp - shape is represented as a compressed path string with 5 digits of precision
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
  • simple - WKT standard for Simple Features.

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder.
See the Simple Features Wiki description page for more detail. 		shapeFormat: "raw" <shapeFormat>raw</shapeFormat>
currentPage
Integer		 The current page of the results. currentPage: 1 <currentPage>1</currentPage>
pageSize
Integer		 If a page size was set on the request, this is the number of results to return in the request. pageSize: 10 <pageSize>10</pageSize>
pageKey
String		 If a pageSize is set, then the key to retrieve other pages will be returned. Refer to the Paging documentation for more details. pageKey: "0ba1e4a3-8fdc-4e68-9349-33086b83b2ef" <pageKey>0ba1e4a3-8fdc-4e68-9349-33086b83b2ef</pageKey>
mapData
MapData		 A map data layer to search against 

{
  "name":"navt",
  "dts":[753,800]
}

<mapData>
  <name>navt</name>
  <dts>
	<dt>753</dt>
	<dt>800</dt>
  </dts>
</mapData>
remoteData
RemoteData		 A list of remote data to search against 

{
  "key":"1",
  "shapePoints":["40.099998","-76.305603"],
  "name":"point"
}


<remoteData>
  <key>1</key>
  <name>point</name>
  <shapePoints>
	<latLng>
	  <lat>40.099998</lat>
	  <lng>-76.305603</lng>
	</latLng>
  </shapePoints>
</remoteData>
hostedData
HostedData		 A list of hosted data sources to search against 

{
  "name":"MQA.test",
  "extraCiteria":"city='lancaster'",
  "fields":[
	"Address1",
	"Address2",
	"City",
	"State",
	"Country",
	"Phone"
  ]
}


<hostedData>
  <name>MQA.test</name>
  <extraCriteria>city='lancaster'</extraCriteria>
  <fields>
	<field>Address1</field>
	<field>Address2</field>
	<field>City</field>
	<field>State</field>
	<field>Country</field>
	<field>Phone</field>
  </fields>
</hostedData>
resultsCount
Integer		 The number of total results found, this includes the cached paged items. resultsCount: 8 <resultsCount>8</resultsCount>
searchResult
SearchResult		 The results of the search request. Refer below to the SearchResult object documentation for details. 

{
  "key":"282820",
  "name":"Heritage Ctr Museum-Lancaster Cnty",
  "sourceName":"MQA.test",
  "shapePoints":["40.037769","-76.30661"],
  "distanceUnit":"m",
  "distance":0.042897,
  "resultNumber":1,
  "fields":[
	{"State":"PA"},
	{"Address1":"W King St"},
	{"Country":"US"},
	{"City":"Lancaster"},
	{"Phone":""},
	{"Address2":""}
  ]
}


<searchResult>
  <key>282820</key>
  <name>Heritage Ctr Museum-Lancaster Cnty</name>
  <resultNumber>1</resultNumber>
  <distance>0.042897</distance>
  <distanceUnit>m</distanceUnit>
  <sourceName>MQA.test</sourceName>
  <shapePoints>
	<latLng>
	  <lat>40.037769</lat>
	  <lng>-76.30661</lng>
	</latLng>
  </shapePoints>
  <fields>
	<State>PA</State>
	<Address1>W King St</Address1>
	<Country>US</Country>
	<City>Lancaster</City>
	<Phone/>
	<Address2/>
  </fields>
</searchResult>

Search Result

The following table describes the parameters returned in a Search Result Object

Name Description
key
String		 the unique identifier for the search result in it's source.
name
String		 the name of the result.
resultNumber
Integer		 the number of the result through all search results, even paged data.
distance
Double		 the distance from the center of the search area.
  • radius - center point
  • rectangle - center of the rectangle
  • polygon - centroid of the polygon
  • corridor - closest point to the result on the line
distanceUnit
String		 Specifies the type of units for the distance. Values are:
  • m - Miles - Sorts the results by straight line distance in miles (straight line distance).
  • k - Kilometers - Sorts the results by straight line distance in kilometers (straight line distance).
  • wmin - Walking Minutes - Sorts the results by shortest walking time (calculated as an actual walking route).
  • dmin - Drive Minutes - Sorts the results by shortest driving time (calculated as an actual driving route).
  • dm - Drive Miles - Sorts the results by shortest driving distance in miles (calculated as an actual driving route).
  • dk - Drive Kilometers - Sorts the results by shortest driving distance in kilometers (calculated as an actual driving route).
sourceName
String		 The name of the source
  • hosted - the name of the hosted set searched
  • map - the name of the map data layer searched
  • remote - "remote" will always be returned
shapePoints
Geometry		 The shape of the remote data object
fields
Field[]		 This is a list of key/value pairs from the hosted data source.

Search Result Example

Type Example
JSON 

{
  "key":"282820",
  "name":"Heritage Ctr Museum-Lancaster Cnty",
  "sourceName":"MQA.test",
  "shapePoints":["40.037769","-76.30661"],
  "distanceUnit":"M",
  "distance":0.042897,
  "resultNumber":1,
  "fields":[
	{"State":"PA"},
	{"Address1":"W King St"},
	{"Country":"US"},
	{"City":"Lancaster"},
	{"Phone":""},
	{"Address2":""}
  ]
}
XML 

<searchResult>
  <key>282820</key>
  <name>Heritage Ctr Museum-Lancaster Cnty</name>
  <resultNumber>1</resultNumber>
  <distance>0.042897</distance>
  <distanceUnit>M</distanceUnit>
  <sourceName>MQA.test</sourceName>
  <shapePoints>
  <latLng>
	<lat>40.037769</lat>
	<lng>-76.30661</lng>
  </latLng>
  </shapePoints>
  <fields>
	<State>PA</State>
	<Address1>W King St</Address1>
	<Country>US</Country>
	<City>Lancaster</City>
	<Phone/>
	<Address2/>
  </fields>
</searchResult>
  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use