Appearance

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:

FormatExample
city (AA5), state (AA3)Denver, CO
city, state, postalCodeDenver, CO, 80202
postalCode80202
street, city, state1555 Blake St, Denver, CO
street, city, state, postalCode1555 Blake St, Denver, CO 80202
street, postalCode1555 Blake St, 80202
latLng39.750307,-104.999472
JSON Object
(See 'Advanced Locations' below for details)		{"street": "1555 Blake St"}

Single-Line Response ​

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

JSON
{
  "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
      }
    }
  ]
}
XML
<locations>
  <location>
    <street>1555 Blake St</street>
    <adminArea6 type="Neighborhood"/>
    <adminArea5 type="City">Denver</adminArea5>
    <adminArea3 type="State">CO</adminArea3>
    <adminArea4 type="County">Denver</adminArea4>
    <postalCode>80202-1625</postalCode>
    <adminArea1 type="Country">US</adminArea1>
    <geocodeQuality>POINT</geocodeQuality>
    <geocodeQualityCode>P1AAA</geocodeQualityCode>
    <dragPoint>false</dragPoint>
    <sideOfStreet>N</sideOfStreet>
    <displayLatLng>
      <latLng>
        <lat>39.750307</lat>
        <lng>-104.999472</lng>
      </latLng>
    </displayLatLng>
    <linkId>fcc83bcc-4794-4b89-ab79-8058919d70b5</linkId>
    <unknownInput/>
    <type>s</type>
    <latLng>
      <lat>39.750307</lat>
      <lng>-104.999472</lng>
    </latLng>
  </location>
</locations>

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 ​

FieldDescriptionRequired
key
String		The API Key.Yes
latLng
String		Returns the latitude, longitude for routing and is the nearest point on a road for the entrance.Yes
street
String		Street address - (If this is the only parameter given in a Location object, a single-line address location will be made from this parameter)Yes
adminArea5 or city
String		City nameYes
adminArea4 or county
String		County nameYes
adminArea3 or state
String		State nameYes
adminArea1 or county
String		Country nameYes
postalCode
String		Postal codeYes
type
String		Type of location.
  • s - stop (default)
  • v - via
Yes
dragPoint
Boolean		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)		No

5-Box Input Response ​

JSON
{
  "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
      }
    }
  ]
}
XML
<locations>
  <location>
    <street>1555 Blake St</street>
    <adminArea6 type="Neighborhood"/>
    <adminArea5 type="City">Denver</adminArea5>
    <adminArea3 type="State">CO</adminArea3>
    <adminArea4 type="County">Denver</adminArea4>
    <postalCode>80202-1625</postalCode>
    <adminArea1 type="Country">US</adminArea1>
    <geocodeQuality>POINT</geocodeQuality>
    <geocodeQualityCode>P1AAA</geocodeQualityCode>
    <dragPoint>false</dragPoint>
    <sideOfStreet>N</sideOfStreet>
    <displayLatLng>
      <latLng>
        <lat>39.750307</lat>
        <lng>-104.999472</lng>
      </latLng>
    </displayLatLng>
    <linkId>fcc83bcc-4794-4b89-ab79-8058919d70b5</linkId>
    <unknownInput/>
    <type>s</type>
    <latLng>
      <lat>39.750307</lat>
      <lng>-104.999472</lng>
    </latLng>
  </location>
</locations>

Request Samples ​

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.

JSON
{
  "locations": [
    {
      "street": "1555 Blake St",
      "city": "Denver",
      "county": "Denver",
      "state": "CO"
    },
    {
      "latLng": {
        "lat": 39.750307,
        "lng": -104.999472
      }
    }
  ]
}
XML
<locations>
  <location>
    <street>1555 Blake St</street>
    <city>Denver</city>
    <county>Denver</county>
    <state>CO</state>
  </location>
  <location>
    <latLng>
      <lat>39.750307</lat>
      <lng>-104.999472</lng>
    </latLng>
  </location>
</locations>

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.

JSON
{
  "location": {
    "street": "1555 Blake St",
    "city": "Denver",
    "county": "Denver",
    "state": "CO"
  }
}
XML
<location>
  <street>1555 Blake St</street>
  <city>Denver</city>
  <county>Denver</county>
  <state>CO</state>
</location>

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 NameDescription
displayLatLngA lat/lng pair which can be helpful when showing this address as a Point of Interest.
geocodeQualityThe precision of the geocoded location. L1=Address, Z1=postalCode, etc.
linkIdIdentifies the closest road to the address for routing purposes.
sideOfStreetSpecifies the side of street.

- L - left
- R - right
- N - none (default)

Response Sample ​

JSON
{
  "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
      }
    }
  ]
}
XML
<locations>
  <location>
    <street>1555 Blake St</street>
    <adminArea6 type="Neighborhood"/>
    <adminArea5 type="City">Denver</adminArea5>
    <adminArea3 type="State">CO</adminArea3>
    <adminArea4 type="County">Denver</adminArea4>
    <postalCode>80202-1625</postalCode>
    <adminArea1 type="Country">US</adminArea1>
    <geocodeQuality>POINT</geocodeQuality>
    <geocodeQualityCode>P1AAA</geocodeQualityCode>
    <dragPoint>false</dragPoint>
    <sideOfStreet>N</sideOfStreet>
    <displayLatLng>
      <latLng>
        <lat>39.750307</lat>
        <lng>-104.999472</lng>
      </latLng>
    </displayLatLng>
    <linkId>fcc83bcc-4794-4b89-ab79-8058919d70b5</linkId>
    <unknownInput/>
    <type>s</type>
    <latLng>
      <lat>39.750307</lat>
      <lng>-104.999472</lng>
    </latLng>
  </location>
</locations>