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, 17601
postalCode 17601
street, city, state 300 Granite Run Dr, Lancaster, PA
street, city, state, postalCode 300 Granite Run Dr, Lancaster, PA, 17601
street, postalCode 300 Granite Run Dr, 17601
latLng 40.07546,-76.329999
JSON Object
(See below for details)		 {street: "Boalsburg, PA"}

Advanced Locations

Using JSON or XML as your input format allows a higher degree of address specification than with single-line input.

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 Parameters

Field Name Description
latLng Returns the latitude, longitude for routing and is the nearest point on a road for the entrance.
street 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 City name
city City name
adminArea4 County name
county County name
adminArea3 State name
state State name
adminArea1 Country name
country Country name
postalCode Postal code
type Type of location.
  • s - stop (default)
  • v - via
dragPoint 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)

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: "300 granite run dr",
         city: "lancaster",
         county: "lancaster",
         state: "pa"
      },
      {
         latLng:
         {
            lat: 39.900799,
            lng: -76.606102
         }
      }
   ]
}

<locations>
   <location>
      <street>300 granite run dr</street>
      <city>lancaster</city>
      <county>lancaster</county>
      <state>pa</state>
   </location>
   <location>
      <latLng>
         <lat>39.900799</lat>
         <lng>-76.606102</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: "300 granite run dr",
      city: "lancaster",
      county: "lancaster",
      state: "pa"
   }
}

<location>
   <street>300 granite run dr</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: -77.792801,
      lat: 40.7756
   },
   displayLatLng: {
      lng: -77.793,
      lat: 40.776
   },
   adminArea4: "Centre County",
   adminArea5Type: "City",
   adminArea4Type: "County",
   adminArea5: "Boalsburg",
   street: "",
   adminArea1: "US",
   adminArea3: "PA",
   type: "s",
   linkId: 98178502,
   postalCode: "",
   sideOfStreet: "N",
   dragPoint: false,
   adminArea1Type: "Country",
   geocodeQuality: "CITY",
   adminArea3Type: "State"
}

<location>
   <street/>
   <adminArea5 type="City">
      Boalsburg
   </adminArea5>
   <adminArea3 type="State">
      PA
   </adminArea3>
   <adminArea4 type="County">
      Centre County
   </adminArea4>
   <postalCode/>
   <adminArea1 type="Country">
      US
   </adminArea1>
   <geocodeQuality>
      CITY
   </geocodeQuality>
   <dragPoint>false</dragPoint>
   <sideOfStreet>N</sideOfStreet>
   <linkId>98178502</linkId>
   <type>s</type>
   <latLng>
      <lat>40.7756</lat>
      <lng>-77.792801</lng>
   </latLng>
   <displayLatLng>
      <lat>40.776</lat>
      <lng>-77.793</lng>
   </displayLatLng>   
</location>
  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use