Specifying Locations

Single Line Locations

When using key/value pairs as input, single-line locations are all that can be given. The following single-line address formats are supported:

Format Example
city (AA5), state (AA3) Denver, CO
city, state, postalCode Denver, CO, 80202
postalCode 80202
street, city, state 1555 Blake St, Denver, CO
street, city, state, postalCode 1555 Blake St, Denver, CO 80202
street, postalCode 1555 Blake St, 80202
latLng 39.750307,-104.999472
JSON Object
(See below for details)		 {"street": "1555 Blake St"}

Single-Line Response

GET

https://www.mapquestapi.com/geocoding/v1/address?key=KEY&location=1555%20Blake%20St,%20Denver,%20CO%2080202&thumbMaps=false

{
  "locations": [
    {
      "street": "1555 Blake St",
      "adminArea6": "",
      "adminArea6Type": "Neighborhood",
      "adminArea5": "Denver",
      "adminArea5Type": "City",
      "adminArea4": "Denver",
      "adminArea4Type": "County",
      "adminArea3": "CO",
      "adminArea3Type": "State",
      "adminArea1": "US",
      "adminArea1Type": "Country",
      "postalCode": "80202-1625",
      "geocodeQualityCode": "P1AAA",
      "geocodeQuality": "POINT",
      "dragPoint": false,
      "sideOfStreet": "N",
      "linkId": "fcc83bcc-4794-4b89-ab79-8058919d70b5",
      "unknownInput": "",
      "type": "s",
      "latLng": {
        "lat": 39.750307,
        "lng": -104.999472
      },
      "displayLatLng": {
        "lat": 39.750307,
        "lng": -104.999472
      }
    }
  ]
}

Advanced Locations

The 5-Box Input address format (which is compatible with JSON and XML), allows for a higher degree of address specification by entering the full address in its individual location parameters. The 5-Box Input format is beneficial as it bypasses the parsing functionality of the single-line request.

To specify locations in JSON or XML, you must include a locations parameter that encloses a list of locations. It is locations:[ and ] in JSON, or <locations> and </locations> in XML. The contents of the locations must be Location objects.

Location objects are either

  • Strings, which are assumed to be single-line addresses (as described above), or
  • Location objects, which are JSON objects containing the parameters described in the table below.

Request and Response Parameters

Field Required? Description
key
String		 Yes The API Key.
latLng
String		 Yes Returns the latitude, longitude for routing and is the nearest point on a road for the entrance.
street
String		 Yes Street address - (If this is the only parameter given in a Location object, a single-line address location will be made from this parameter)
adminArea5 or city
String		 Yes City name
adminArea4 or county
String		 Yes County name
adminArea3 or state
String		 Yes State name
adminArea1 or country
String		 Yes Country name
postalCode
String		 Yes Postal code
type
String		 Yes Type of location.
  • s - stop (default)
  • v - via
dragPoint
Boolean 		No Is location a drag point? This option only applies when making a dragroute call.
  • true - location is a drag point
  • false - location is not a drag point (default)

5-Box Input Response

{
  "locations": [
    {
      "street": "1555 Blake St",
      "adminArea6": "",
      "adminArea6Type": "Neighborhood",
      "adminArea5": "Denver",
      "adminArea5Type": "City",
      "adminArea4": "Denver",
      "adminArea4Type": "County",
      "adminArea3": "CO",
      "adminArea3Type": "State",
      "adminArea1": "US",
      "adminArea1Type": "Country",
      "postalCode": "80202-1625",
      "geocodeQualityCode": "P1AAA",
      "geocodeQuality": "POINT",
      "dragPoint": false,
      "sideOfStreet": "N",
      "linkId": "fcc83bcc-4794-4b89-ab79-8058919d70b5",
      "unknownInput": "",
      "type": "s",
      "latLng": {
        "lat": 39.750307,
        "lng": -104.999472
      },
      "displayLatLng": {
        "lat": 39.750307,
        "lng": -104.999472
      }
    }
  ]
}

Request Sample

Below is an example of forming a Locations object. This would be used for getting Directions, doing Batch Geocoding, or creating search areas from multiple locations in the Search Service. 

{
  "locations": [
    {
      "street": "1555 Blake St",
      "city": "Denver",
      "county": "Denver",
      "state": "CO"
    },
    {
      "latLng": {
        "lat": 39.750307,
        "lng": -104.999472
      }
    }
  ]
}

Below is an example of forming a Location object. All of the services not mentioned above use only one location at a time. Below is how to use just one location. 

{
  "location": {
    "street": "1555 Blake St",
    "city": "Denver",
    "county": "Denver",
    "state": "CO"
  }
}

Response Parameters

In addition to the parameters listed above, there are several attributes of a Location object which are return-only. You might see these attributes in the response from a service call, but they are not settable attributes and are therefore ignored if supplied as input.

Field Name Description
displayLatLng A lat/lng pair which can be helpful when showing this address as a Point of Interest.
geocodeQuality The precision of the geocoded location. L1=Address, Z1=postalCode, etc.
geocodeQualityCode The five character quality code for the precision of the geocoded location. See the Geocode Quality reference page for more information.
linkId Identifies the closest road to the address for routing purposes.
sideOfStreet Specifies the side of street.
  • L - left
  • R - right
  • N - none (default)

Response Sample

{
  "locations": [
    {
      "street": "1555 Blake St",
      "adminArea6": "",
      "adminArea6Type": "Neighborhood",
      "adminArea5": "Denver",
      "adminArea5Type": "City",
      "adminArea4": "Denver",
      "adminArea4Type": "County",
      "adminArea3": "CO",
      "adminArea3Type": "State",
      "adminArea1": "US",
      "adminArea1Type": "Country",
      "postalCode": "80202-1625",
      "geocodeQualityCode": "P1AAA",
      "geocodeQuality": "POINT",
      "dragPoint": false,
      "sideOfStreet": "N",
      "linkId": "fcc83bcc-4794-4b89-ab79-8058919d70b5",
      "unknownInput": "",
      "type": "s",
      "latLng": {
        "lat": 39.750307,
        "lng": -104.999472
      },
      "displayLatLng": {
        "lat": 39.750307,
        "lng": -104.999472
      }
    }
  ]
}