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 Formats JSON
Authentication Yes (Requires Key)
Rate Limited Yes

Request Parameters

  • key required

    The API Key, which is needed to make requests to MapQuest services.

  • q required

    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.

  • collection required

    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.

  • limit optional, default is 10

    The maximum number of results to return. Must lie in the range [1, 15].

  • location optional

    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.

  • countryCode optional

    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.

  • feedback optional

    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.

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

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

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