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" } } } ] }