Specifying Locations

The Mapquest Platform Services all use locations. The following documentation is to explain different ways locations can be formed across all the services offered.

Contents

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) Lancaster, PA
city, state, postalCode Lancaster, PA, 17603
postalCode 17603
street, city, state 1090 N Charlotte St, Lancaster, PA
street, city, state, postalCode 1090 N Charlotte St, Lancaster, PA 17603
street, postalCode 1090 N Charlotte St, 17603
latLng 40.05323,-76.313632
JSON Object
(See below for details)
{"street": "1090 N Charlotte St"}

Single-Line Response

JSON Example XML Example
{
   "locations":[
      {
         "adminArea4": "Lancaster",
          "adminArea5Type":"City",
         "adminArea4Type":"County",
         "adminArea5":"Lancaster",
         "street":"1090 N Charlotte St",
         "adminArea1":"US",
         "adminArea3":"PA",
         "type":"s",
         "displayLatLng":{
            "lng":-76.313632,
            "lat":40.05323
         }
         "postalCode":"17603",
         "dragPoint":false,
         "adminArea1Type":"Country",
         "adminArea3Type":"State"
      }
   ]
}

<locations>
   <location>
      <street>1090 N Charlotte St</street>
      <adminArea5 type="City">Lancaster</adminArea5>
      <adminArea3 type="State">PA</adminArea3>
      <adminArea4 type="County">Lancaster</adminArea4>
      <postalCode>17603</postalCode>
      <adminArea1 type="Country">US</adminArea1>
      <dragPoint>false</dragPoint>
      <displayLatLng>
         <latLng>
            <lat>40.05323</lat>
            <lng>-76.313632</lat>
         </latLng>
      </displayLatLng>
   </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

Field Required Description
key
String
Yes The application 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

JSON Example XML Example
{
   "locations":[
      {
         "adminArea4": "Lancaster",
          "adminArea5Type":"City",
         "adminArea4Type":"County",
         "adminArea5":"Lancaster",
         "street":"1090 N Charlotte St",
         "adminArea1":"US",
         "adminArea3":"PA",
         "type":"s",
         "displayLatLng":{
            "lng":-76.313632,
            "lat":40.05323
         }
         "postalCode":"17603",
         "dragPoint":false,
         "adminArea1Type":"Country",
         "adminArea3Type":"State"
      }
   ]
}

<locations>
   <location>
      <street>1090 N Charlotte St</street>
      <adminArea5 type="City">Lancaster</adminArea5>
      <adminArea3 type="State">PA</adminArea3>
      <adminArea4 type="County">Lancaster</adminArea4>
      <postalCode>17603</postalCode>
      <adminArea1 type="Country">US</adminArea1>
      <dragPoint>false</dragPoint>
      <displayLatLng>
         <latLng>
            <lat>40.05323</lat>
            <lng>-76.313632</lat>
         </latLng>
      </displayLatLng>
   </location>
</locations>

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.

JSON Request Example XML Request Example
{
   "locations":
   [
      {
         "street": "1090 N Charlotte St",
         "city": "Lancaster",
         "county": "Lancaster",
         "state": "PA"
      },
      {
         "latLng":
         {
            "lat": 40.05323,
            "lng": -76.313632
         }
      }
   ]
}
<locations>
   <location>
      <street>1090 N Charlotte St</street>
      <city>Lancaster</city>
      <county>Lancaster</county>
      <state>PA</state>
   </location>
   <location>
      <latLng>
         <lat>40.05323</lat>
         <lng>-76.313632</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 Request Example XML Request Example
{
   "location":
   {
      "street": "1090 N Charlotte St",
      "city": "Lancaster",
      "county": "Lancaster",
      "state": "PA"
   }
}
<location>
   <street>1090 N Charlotte St</street>
   <city>Lancaster</city>
   <county>Lancaster</county>
   <state>PA</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 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

JSON Response Example XML Response Example
{
   "latLng": {
      "lng": -76.313603,
      "lat": 40.053116
   },
   "displayLatLng": {
      "lng": -76.313603,
      "lat": 40.053116
   },
   "adminArea4": "Lancaster",
   "adminArea5Type": "City",
   "adminArea4Type": "County",
   "adminArea5": "Lancaster",
   "street": "",
   "adminArea1": "US",
   "adminArea3": "PA",
   "type": "s",
   "linkId": "85659004i119689974r154056625",
   "postalCode": "",
   "sideOfStreet": "L",
   "dragPoint": false,
   "adminArea1Type": "Country",
   "geocodeQuality": "ADDRESS",
   "geocodeQualityCode": "L1AAA"
   "adminArea3Type": "State"
   "unknownInput": ""
}
<location>
   <street/>
   <adminArea5 type="City">
      Lancaster
   </adminArea5>
   <adminArea3 type="State">
      PA
   </adminArea3>
   <adminArea4 type="County">
      Lancaster
   </adminArea4>
   <postalCode>
      17603
   </postalCode>
   <adminArea1 type="Country">
      US
   </adminArea1>
   <geocodeQuality>
      ADDRESS
   </geocodeQuality>
   <geocodeQualityCode>
      L1AAA
   </geocodeQualityCode>
   <unknownInput/>
   <dragPoint>false</dragPoint>
   <sideOfStreet>L</sideOfStreet>
   <linkId>85659004i119689974r154056625</linkId>
   <type>s</type>
   <latLng>
      <lat>40.053116</lat>
      <lng>-76.313603</lng>
   </latLng>
   <displayLatLng>
      <lat>40.053116</lat>
      <lng>-76.313603</lng>
   </displayLatLng>   
</location>
  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use