Search Ahead API V5 beta
GET Prediction
This endpoint returns a list of suggestions, or predictions, based on two or more characters provided with the request. V5 supports international search capabilities.
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 |
| 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 |
| languageCode | The language code for the response. Supports ISO 639-1 language codes. | no, default is en |
The GeoJSON specification is described here: https://geojson.org/
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. |
| id | A string that includes the a MapQuest-specific unique identifier. Results from all collections include an ID. |
| language | A string that contains the ISO 639-1 language code of the result that is returned. Possible values include: en. |
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
GET https://mapquestapi.com/search/v5/prediction?key=KEY&limit=7&q=San Francisco&location=-96.73431873321533,33.12551193423172&languageCode=en
cURL Request
curl -X GET -H "Accept: application/json" "https://mapquestapi.com/search/v5/prediction?key=KEY&limit=7&q=San Francisco&location=-96.73431873321533,33.12551193423172&languageCode=en"
Example Response
JSON
{
"request": {
"q": "San Francisco",
"limit": 7,
"languageCode": "en",
"location": {
"long": "-96.73431873321533",
"lat": "33.12551193423172"
}
},
"results": [
{
"id": "Y206bmFtZWRwbGFjZToyMTAxMDIzMw==",
"displayString": "San Francisco, CA, United States",
"name": "San Francisco, CA, United States",
"language": "en",
"recordType": "city",
"place": {
"type": "Feature",
"geometry": {
"coordinates": [
-122.41966,
37.77712
],
"type": "Point"
},
"properties": {
"city": "San Francisco",
"state": "California",
"stateCode": "CA",
"postalCode": "94102",
"county": "San Francisco",
"country": "United States",
"countryCode": "USA",
"type": "address"
}
}
}
]
}