Skip to content

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

https://www.mapquestapi.com/search/v3/prediction

Resource Information

Response FormatsJSON
AuthenticationYes (Requires Key)
Rate LimitedYes

Request Parameters

Request ParameterDescriptionRequired
keyThe API Key, which is needed to make requests to MapQuest services.yes
qA 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
collectionSearch 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
limitThe maximum number of results to return. Must lie in the range [1, 15].no, default is 10
locationThe 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
countryCodeThe 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
feedbackIf 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

requestA JSON object containing the parameters and values passed in with the request.

Results Object

displayStringA 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.
nameA string that contains the name of the result that is returned without additional summary information included.
recordTypeA 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.
collectionA 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.
idA string that includes the a MapQuest-specific unique identifier. Results from all collections include an ID. This field replaces the deprecated mqId field.
mqIdPlease 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.
languageA string that contains the ISO 639-1 language code of the result that is returned. Possible values are: en.
slugA 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

typeA string that describes the type of GeoJSON object associated with the result that is returned. Possible values are: Feature.

Geometry Object

coordinatesA 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.
typeA string that represents the type of GeoJSON feature for the result that is returned. Possible values are: Point.

Properties Object

typeThe type of address entity relevant to this location. Possible values are: address, neighborhood, postalCode, city, county, state, country.
streetA string that contains the street address of this location, if applicable to the result returned.
cityA string that contains the enclosing city of this location, if applicable to the result returned.
stateA string that contains the enclosing state or province of this location, if applicable to the result returned.
stateCodeA string that contains the enclosing two-character state code of this location, if applicable to the result returned.
countyA string that contains the enclosing county of this location, if applicable to the result returned.
countryA string that contains the enclosing country of this location, if applicable to the result returned.
countryCodeA string that contains the enclosing ISO 3166-1 Alpha-2 country code of this location, if applicable to the result returned.
postalCodeA string that contains the coarsest enclosing postal code, if applicable to the result returned.

Example Request

GET https://www.mapquestapi.com/search/v3/prediction?key=KEY&limit=5&collection=adminArea,poi,address,category,franchise,airport&q=den

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