Open Geocoding Service Developer's Guide

The Open geocoding service enables you to take an address and get the associated latitude and longitude. You can also use any latitude and longitude pair and get the associated address. Three types of geocoding are offered: address, reverse, and batch. Release notes are available here. Comments, feedback, and support questions can be posted in our Support Forums.

Hello, World Example

The following example demonstrates a simple request to get geocode information for Lancaster, PA. The JavaScript code that sends the request and displays the result can be viewed here.

(Results will be displayed below)

Contents

Common URL Parameters

The following table describes the request parameters that are not related to specific Geocode Request options. These parameters, if supplied, must be supplied as request parameters (they can not be supplied in the BODY of the request).

Request Parameter Description
key
String
 A unique key to authorize use of the Routing Service.

This parameter is required.
inFormat Specifies the format of the request. If this parameter is not supplied, the input format is assumed to be JSON-formatted text. The JSON-formatted input text must be supplied as either the "json" parameter of an HTTP GET, or as the BODY of an HTTP POST. If this parameter is "xml", the XML-formatted input text must be supplied as either the "xml" parameter of an HTTP GET, or as the BODY of an HTTP POST.

Must be one of the following, if supplied:
  • json
  • xml
Defaults to "json" when using POST; otherwise it determines which to use based on parameters given.
json This parameter, if present, should contain the JSON-formatted text of the request. Use this parameter if you want to submit your request in JSON format, but do not want to use an HTTP POST to submit body text.

Note: Remember to URL-escape the text in this parameter!
xml This parameter, if present, should contain the XML-formatted text of the request. Use this parameter if you want to submit your request in XML format, but do not want to use an HTTP POST to submit body text.

Note: Remember to URL-escape the text in this parameter!
outFormat Specifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
  • csv (character delimited)
Defaults to "json" if not supplied

Specifying Locations

Depending on the geocode function being called, one or more locations are needed. When using key/value pairs, the Geocoding Service provides a location= parameter that can be used. Multiple location= parameters can be used for Batch Geocoding. JSON and XML use Location objects, which are the same across all the services. Refer to the Locations documentation on how to properly form locations in all formats.

Specifying Country

The geocoding target country can be specified by using the "adminArea1" or "country" request parameter (Refer to the Locations documentation). International designations are also supported with single-line addressing.

Country biasing is additionally provided. Currently, site referral can be used to provide a default country. For a given request, if the "HTTP_REFERER" header is populated with a URI that contains a valid country, that country will be used for geocoding. The default country can be overridden by populating the "adminArea1" request parameter. To use this feature, the country must be part of the top-level-domain name (TLD) and in the standard format (For example: http://www.sitename.co.uk/referringpage/).

Single-line vs. 5-box Input

The 5-box input format allows for a higher degree of address specification by entering the full address already broken down into individual components. The 5-box input format is beneficial as it bypasses the parsing functionality of the single-line request. For more information about additional parameters that can be used with single-line and 5-box requests, refer to theLocations documentation.

The following are sample requests for 1090 N Charlotte St, Lancaster, PA, 17603 shown in single-line and 5-box request formats:

Single-line address format: KVP Request


5-box address format: KVP Request


5-box address format: JSON Request


5-box address format: XML Request


Geocode Options

The following table describes the options that can be set in a Geocode Request.

Request Parameter Description
maxResults
int 		The number of results to limit the response to in the case of an ambiguous address. (-1 indicates no limit)

Default = -1
thumbMaps
Boolean 		This parameter tells the service whether it should return a URL to a static map thumbnail image for a location being geocoded.
  • true - The response will include a URL to a static map image of the geocoded location.
  • false - The response will not include a static map image URL.
Default = true
boundingBox When using batch geocoding or when ambiguous results are returned, any results within the provided bounding box will be moved to the top of the results list. Bounding box format is: upper left latitude, upper left longitude, lower right latitude, lower right longitude.

Refer to the Geocode Options Sample below for examples of how to format this parameter.
ignoreLatLngInput
Boolean 		This option tells the service whether it should fail when given a latitude/longitude pair in an address or batch geocode call, or if it should ignore that and try and geocode what it can.
  • true - The geocoder will ignore the LatLng specified in the location, and use the address info to perform geocode
  • false - The geocoder will return a geoaddress object containing the LatLng passed in and write a warning message to Info block
Default = false (Applies to address and batch calls)
delimiter
Character 		A delimiter is used only when outFormat=csv. The delimiter is the single character used to separate the fields of a character delimited file. The delimiter defaults to a comma(,). The valid choices are:
  • Comma (,) - All fields are quoted when comma is used.
  • Pipe (|) - The fields are not quoted when pipes are used.
  • Colon (:) - All fields are quoted when colon is used.
  • Semicolon (;) - All fields are quoted when semicolon is used.
Default = comma

 

Geocode Options Sample


Option Value(s) Notes
Location:
boundingBox:
If the "Ambiguous (With boundingBox)" option is selected, the boundingBox used will be: UL: 39.715056, -75.811158, LR: 39.5098, -75.491781, an area which includes Red Lion, DE.
Changing this from "None" will change the location text
Notice: Having the boundingBox will change the order of the locations so locations within the bounding box region are pushed to the top of the list. (In this case, the boundingBox covers the upper portion of Delaware, so the result located in Delaware is moved to the top of the list)
thumbMaps:  
maxResults: This option will only have an effect if the location above is ambiguous
Input Format: Uses "json=" or "xml=" if appropriate.
Output Format: Default is JSON (Currently only JSON works)
Delimiter: Default is none. This option will only have an effect if outFormat=csv.

(Output will be displayed below)

Geocode Response

Response Field Description JSON Example Return Value(s) XML Example Return Value(s)
providedLocation The provided location properties passed in the geocode request. Includes any properties not directly related to a standard address (For example, id, business name) 
{  
  "providedLocation": {
  "id": 12,
  "location": "Lancaster, PA",
  "name": "My Location"
  }
}

<providedLocation>
    <id>12</id>
    <location>Lancaster, PA</location>
    <name>My Location</name>
</providedLocation>
latLng Returns the latitude/longitude for routing and is the nearest point on a road for the entrance. 
{
    "latLng": {
        "lng": -76.313603,
        "lat": 40.053116
    }
}

                 
<latLng>
    <lat>40.053116</lat>
    <lng>-76.313603</lng>
</latLng>
street Street address 
{
    "street": "1090 N Charlotte St"
}

<street>1090 N Charlotte St</street>
adminArea6 Neighborhood name 
{
    "adminArea6": "Champs-Élysées"
}

<adminArea6 type="Neighborhood">Champs-Élysées</adminArea6>
adminArea5 City name 
{
    "adminArea5": "Lancaster"
}

<adminArea5 type="City">Lancaster</adminArea5>
adminArea4 County name 
{
    "adminArea4": "Lancaster"
}

<adminArea4 type="County">Lancaster</adminArea4>
adminArea3 State name 
{
    "adminArea3": "PA"
}

<adminArea3 type="State">PA</adminArea3>
adminArea1 Country name 
{
    "adminArea1": "US"
}

<adminArea1 type="Country">US</adminArea1>
postalCode Postal code 
{
    "postalCode": "17603"
}

<postalCode>17603</postalCode>
type Type of location.
  • 's' = stop (default)
  • 'v' = via
 
{
    "type": 's'
}

<type>s</type>
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)
 
{
    "dragPoint": false
}

<dragPoint>false</dragPoint>
displayLatLng A lat/lng pair that can be helpful when showing this address as a Point of Interest. 
{
    "displayLatLng": {
        "lng": -76.313603,
        "lat": 40.053116
    }
}

<displayLatLng>
  <latLng>
    <lat>40.053116</lat>
    <lng>-76.313603</lng>
  </latLng>
</displayLatLng>
geocodeQuality The precision of the geocoded location. Refer to the Geocode Quality reference page for more information. 
{
    "geocodeQuality": "ADDRESS"
}

<geocodeQuality>ADDRESS</geocodeQuality>
geocodeQualityCode The five character quality code for the precision of the geocoded location. Refer to the Geocode Quality reference page for more information. 
{
    "geocodeQualityCode": "L1AAA"
}

<geocodeQualityCode>L1AAA</geocodeQualityCode>
linkId String that identifies the closest road to the address for routing purposes. 
{
    "linkId": "fcc83bcc-4794-4b89-ab79-8058919d70b5"
}

<linkId>fcc83bcc-4794-4b89-ab79-8058919d70b5</linkId>
sideOfStreet Specifies the side of street.
  • 'L' = left
  • 'R' = right
  • 'N' = none (default)
 
{
    "sideOfStreet": "L"
}

<sideOfStreet>L</sideOfStreet>
info This field contains information about the response.

The statuscode subfield is an integer return value. Refer to the status codes page for more details about our status codes and error messages.

The messages subfield is an array of error messages that describe the status 
{ 
    "info": {
        "statuscode": 400,
        "messages": [
            "Illegal argument from request: 
Insufficient info for location"
        ]
    }
}

<info>
    <statuscode>400</statuscode>
    <messages>
        Illegal argument from request: 
Insufficient info for location
    </messages>
</info>

Reverse Geocode

All the above examples were for Address Geocoding. Reverse Geocoding is also available by inputting a latitude and longitude.

Request Parameter Description Accepted Request Data Required
lat The latitude of the point to reverse geocode 40.053116 Yes
lng The longitude of the point to reverse geocode. -76.313603 Yes

The following example demonstrates a simple request to get geocode information for a latitude/longitude of 40.053116,-76.313603. The JavaScript code which sends the request and displays the result can be viewed here.

Reverse Geocode Sample



Latitude: Longitude:

inFormat:

(Results will be displayed below)

Batch Geocode

The batch geocoding service allows multiple locations to be geocoded at the same time. A limit of 100 locations exists for one call.

The following example demonstrates various ways to make a batch geocode call. The JavaScript code that sends the request and displays the result can be viewed here.

Batch Geocode Sample


Option Value(s) Notes
Location 1:
Location 2:
Location 3:
Location 4:
boundingBox:

If the "Ambiguous with boundingBox" option is selected, the boundingBox used will be: UL: 39.715056, -75.811158, LR: 39.5098, -75.491781, an area which includes Red Lion, DE.

Having the boundingBox will change the order of the locations so locations within the bounding box region are pushed to the top of the list
thumbMaps:  
maxResults: This option will only have an effect on the second location because it is ambiguous
Input Format: Uses "json=" or "xml=" if appropriate.
Output Format: Default is JSON (Currently only JSON works in this sample)
Delimiter: Default is none. This option will only have an effect if outFormat=csv.

(Output will be displayed below)

OpenStreetMap data is licensed under the Open Data Commons Open Database License (ODbL).

  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use