Search Ahead API
GET Prediction
This endpoint returns a list of suggestions, or predictions, based on two or more characters provided with the request.
Resource URL
Resource Information
| Response Formats | JSON |
| Authentication | Yes (Requires Key) |
| Rate Limited | Yes |
Request Parameters
| Request Parameter | Description | Required |
|---|---|---|
| key | The API Key, which is needed to make requests to MapQuest services. | yes |
| q | A query phrase. The phrase can be incomplete, in which case its last term is treated as a prefix during matching. Address queries must begin with a street number. Minimum Length: 2 characters. Maximum Length: 100 characters. | yes |
| collection | Search Ahead organizes types of data into collections, which can be requested using this parameter. The following collections are currently supported: address, adminArea, airport, category, franchise, and poi.This parameter accepts multiple instances of the parameter and or a comma-delimited list. | yes |
| limit | The maximum number of results to return. Must lie in the range [1, 15]. | no, default is 10 |
| location | The geographic context used for searching, ranking, and ordering results. Supports a point defining the geographic "center" of the query. Must consist of two comma-separated floating-point values: the longitude, latitude; the first coordinate must lie in the range [-180, 180], and the second must lie in the range [-90, 90]. While this parameter is not required, it is highly recommended that it be provided in order to improve relevance of results. | no |
| countryCode | The countries to search over. Can contain any valid ISO 3166-1 Alpha-2 country codes. If provided, the search will only return results in the specified countries. Accepts multiple instances of the parameter and or a comma-delimited list. | no |
| feedback | If set to true, generated feedback URI templates will be returned in the response. For more information on providing feedback, see the Providing Feedback page. | no |
The GeoJSON specification is described here: https://geojson.org/
Request Headers
| x-mq-user-id optional (though required for successful use of the feedback API) | A header containing an anonymous user id, consistent over time. This could be, for instance, a device id, advertising id, or persistent browser cookie. |
Response Object
| request | A JSON object containing the parameters and values passed in with the request. |
Results Object
| displayString | A string that contains a summary of the result that is returned. Depending on the type of result returned, the displayString could include a name, street, city, state, and postal code. |
| name | A string that contains the name of the result that is returned without additional summary information included. |
| recordType | A string that contains information about the type of result that is returned. Possible values are: address, airport, poi, postalCode, neighborhood, city, county, state, country, category, franchise. |
| collection | A array of strings that include the name of the collection or collections from which the result was served. Possible values are: address, adminArea, airport, category, franchise, poi. |
| id | A string that includes the a MapQuest-specific unique identifier. Results from all collections include an ID. This field replaces the deprecated mqId field. |
| mqId | Please note: this response is now deprecated. Please use id, detailed above. A number that includes the a MapQuest-specific unique identifier, if applicable to the result. Generally returned with results served from the airport and poi collections. |
| language | A string that contains the ISO 639-1 language code of the result that is returned. Possible values are: en. |
| slug | A string that contains a URL path fragment that will link to a specific address, admin area, or POI on MapQuest.com and may include additional information like reviews and business hours of operation if applicable to the type of result returned. |
Place Object
| type | A string that describes the type of GeoJSON object associated with the result that is returned. Possible values are: Feature. |
Geometry Object
| coordinates | A array of numbers that contains the longitude and latitude that describes the geographic location of the result that is returned. Note: poi results contain a longitude and latitude pair intended to be used for display purposes only. |
| type | A string that represents the type of GeoJSON feature for the result that is returned. Possible values are: Point. |
Properties Object
| type | The type of address entity relevant to this location. Possible values are: address, neighborhood, postalCode, city, county, state, country. |
| street | A string that contains the street address of this location, if applicable to the result returned. |
| city | A string that contains the enclosing city of this location, if applicable to the result returned. |
| state | A string that contains the enclosing state or province of this location, if applicable to the result returned. |
| stateCode | A string that contains the enclosing two-character state code of this location, if applicable to the result returned. |
| county | A string that contains the enclosing county of this location, if applicable to the result returned. |
| country | A string that contains the enclosing country of this location, if applicable to the result returned. |
| countryCode | A string that contains the enclosing ISO 3166-1 Alpha-2 country code of this location, if applicable to the result returned. |
| postalCode | A string that contains the coarsest enclosing postal code, if applicable to the result returned. |
Example Request
cURL Request
curl -X GET -H "Accept: application/json" -H "x-mq-user-id: ABC-123" "https://www.mapquestapi.com/search/v3/prediction?key=KEY&limit=5&collection=adminArea,poi,address,category,franchise,airport&q=den"
Example Response
JSON
{
"request": {
"q": "den",
"limit": 5,
"feedback": false,
"collection": [
"category",
"airport",
"address",
"franchise",
"adminArea"
]
},
"results": [
{
"id": "mqId:10002325",
"displayString": "Denver International Airport (DEN), 8500 Pena Blvd, Denver, CO",
"name": "Denver International Airport (DEN)",
"recordType": "airport",
"collection": [
"airport"
],
"mqId": 10002325,
"slug": "/us/colorado/denver-international-airport-den-10002325",
"language": "en",
"place": {
"type": "Feature",
"geometry": {
"coordinates": [
-104.671828,
39.840072
],
"type": "Point"
},
"properties": {
"city": "Denver",
"stateCode": "CO",
"postalCode": "80249",
"countryCode": "US",
"street": "8500 Pena Blvd",
"type": "address"
}
}
},
{
"id": "category:86dce0d7ad4a3ed7c158bd5184e9f279",
"sic": [
"802101"
],
"displayString": "Dentists",
"name": "Dentists",
"recordType": "category",
"collection": [
"category"
],
"language": "en"
},
{
"id": "category:47f912daf76a0014c575a8cde009f198",
"sic": [
"581208F97"
],
"displayString": "Denny's",
"name": "Denny's",
"recordType": "franchise",
"collection": [
"franchise"
],
"language": "en"
},
{
"id": "mqId:282932003",
"displayString": "Denver County, CO, US",
"name": "Denver County",
"recordType": "county",
"collection": [
"adminArea"
],
"slug": "/us/co/denver-county",
"language": "en",
"place": {
"type": "Feature",
"geometry": {
"coordinates": [
-104.984853,
39.738453
],
"type": "Point"
},
"properties": {
"countryCode": "US",
"county": "Denver County",
"type": "county",
"stateCode": "CO"
}
}
},
{
"id": "mqId:282041090",
"displayString": "Denver, Denver County, CO, US",
"name": "Denver",
"recordType": "city",
"collection": [
"adminArea"
],
"slug": "/us/co/denver",
"language": "en",
"place": {
"type": "Feature",
"geometry": {
"coordinates": [
-104.984853,
39.738453
],
"type": "Point"
},
"properties": {
"city": "Denver",
"stateCode": "CO",
"county": "Denver County",
"countryCode": "US",
"type": "city"
}
}
}
]
}