Geocoding Service Developer's Guide

The 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.

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" if not supplied
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
  • file (character delimited)
Defaults to "json" if not supplied

Specifying Locations

The table below shows the parameters that can be used to specify a location.

Request Parameter Description Example Request Data Required
location A single-line address to be geocoded 300 Granite Run Dr, Lancaster, PA Yes, or alternately use parameters for the individual address parts (see below).
street The street name 300 Granite Run Dr No
postalCode The postal code 17601 No
adminArea5 The locality name. You can also use "city" for this parameter name. Lancaster No
adminArea4 The county name. You can also use "county" for this parameter name. Lancaster County No
adminArea3 The region name. You can also use "state" for this parameter name. PA No
adminArea1 The country name. You can also use "country" for this parameter name. US No

When using Key/Value Pairs, any of the above parameters can be used as a URL request parameter. To use the "location" parameter in JSON or XML, the single-line address must be put into the "street" parameter. Refer to the Geocode Options Sample to see examples of single-line address input.

When using single-line address, the following formats are acceptable.

Format Example
city (AA5), state (AA3) Lancaster, PA
city, state, postcode Lancaster, PA, 17601
postcode 17601
street, city, state 300 Granite Run Dr, Lancaster, PA
street, city, state, postcode 300 Granite Run Dr, Lancaster, PA, 17601
street, postcode 300 Granite Run Dr, 17601
latLng 40.07546,-76.329999
JSON Object {street: "Boalsburg, PA"}

Note: To specify a location in JSON or XML, there must be a "location" parameter. This object will take the form location:{...} in JSON or <location>...</location> in XML. The inner portion of these "location" parameters will be Location objects. When using JSON as a single-line address for a query parameter, the location= parameter in the URL implies a single-line address string or a Location object. For example, here are a few properly formatted locations:

  • JSON - location:{city:"lancaster", state:"pa"}
  • XML - <location><city>lancaster</city><state>pa</state></location>
  • Query Parameters - location=lancaster,pa
  • Query Parameters with JSON - location={city:"lancaster",state:"pa")

Specifying Country

The geocoding target country is specified using the "adminArea1" request parameter. Country designation is currently not supported for single-line addressing. The United States is assumed for all single-line addresses.

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/).

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 teh 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=file. 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: 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=file.

(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.329999
    lat: 40.07546
}

                 
<latLng>
    <lat>40.07546</lat>
    <lng>-76.329999</lng>
</latLng>
street Street address 
street: "Main st."

<street>
    Main St.
</street>
adminArea5 City name 
adminArea5: "Lancaster"

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

<adminArea4 type="County">
    Lancaster County
</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: "17601"

<postalCode>
    17601
</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.728103
    lat: 39.962501
}

<displayLatLng>
    <latLng>
        <lat>39.962501</lat>
        <lng>-76.728103</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 Identifies the closest road to the address for routing purposes. 
linkId: 12345

<linkId>12345</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.0378 Yes
lng The longitude of the point to reverse geocode. -76.305801 Yes

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

Reverse Geocode Sample
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: 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)
Delimiter: Default is none. This option will only have an effect if outFormat=file.

(Output will be displayed below)