Geocode Service API

The Geocode Service API consists of two parts. The first part, the GEOCODE REQUEST API, describes the protocol for making a geocode request. The second part, the GEOCODE RESPONSE API describes the format and content of the response that is returned.

GEOCODE REQUEST API

The geocoder is invoked by submitting a PARAMETER_STRING as an HTTP POST or GET request to:

HOST_URL/geocode_response.exe

The request, in the PARAMETER_STRING form described below, is sent via the HTTP POST method with content-type set to application/x-www-form-urlencoded. The characters are expected to be UTF-8 encoded and the entire request must be less than 4 kilobytes (4096 bytes) in length. The request may also be sent via the HTTP GET method in the following format:

HOST_URL/geocode_response.exe?PARAMETER_STRING

PARAMETER_STRING

The PARAMETER_STRING is composed of variable-value pairs concatenated together with ampersands ( & ). Each variable-value pair consists of a permissable variable name bound with an equal sign ( = ) to a urlencoded client-assigned value. The parameter string will be composed of general parameters which may appear in any request, and of request-specific parameters which will be present or absent, depending on the kind of request. Notwithstanding this distinction, variable-value pairs may appear in the string in any order. The values assigned may be submitted either in upper or lower case letters.

Urlencoded

A value is urlencoded by (a) substituting a plus for a space and (b) subsituting a three-character code for any character not permissable in an http url query string context. This three-character code is composed of a percentage sign (%) followed by the 2 character hexadecimal representation of the character. For example, a forward slash (in a fraction) or ampersand (in a street name such as Joseph & Mary) will need to be urlencoded. Note: some urlencoders substitute %20 (the hexadecimal representation for the space character) for a plus. This should decode correctly. Even so, a plus that is not used as a substitution for a space must be urlencoded.

PARAMETER_STRING example

methodName=GeocodeRequest&Version=1.1&CompleteAddressNumber=1234&CompleteStreetName=W+Main+St&PlaceName=Anywhere

General Request Parameters

The General Request Parameters must or may appear in any request, regardless of the kind of request.

methodName

Required. All requests must include a value for the methodName variable. This value describes the type of request being made. Currently accepted values are:

The method GeocodeRequest is a request to take an unnormalized address and produce a normalized address bound to standard coordinates. The methodName must be a valid query method that the responder can accept. In version 1.1 the only valid methodName is GeocodeRequest. This method is a request for the latitude and longitude of an address for either (a) A site address - the address of a site on a thoroughfare identified by a number, street name, place name and/or postal code - or (b) An intersection address - the intersection of two thoroughfares identified by two street names with place name and/or zip code.

Version

Required. All requests must include a value for the Version. This is a decimal value stating the method Version. This will allow the requester to expect a predictable response. Currently accepted values are:


CountryCode

Required. All requests must include a value for the CountryCode variable.

A string of 2 characters that gives the CountryCode for which the request is applicable. It must be present but the value is ignored in this version.

An example is

.

RequestID

Optional All requests may include a client-assigned value for RequestID. This value, if included, must be a string not less than 1 character and not greater than 255 characters in length. An example is


maximumResponses

Optional All requests may include a value for the variable maximumResponses. This value, if provided, must be a positive integer not less than 1 and not greater than 30. If not given, the default of 30 is used. It controls the number of candidates returned, in the event of an imperfect match. An example of its use is


ResponseFormat

Optional All requests may include a value for the parameter ResponseFormat. Currently accepted values:


Request Specific Parameters

There are two types of GeocodeRequest supported by this responder:

Site Address

A site address is a location denoted by a locale-specific thoroughfare name and an identifier (usually numeric) that positions the location relative to the extent of the thoroughfare.

Intersection Address

An intersection address is the location of the intersection or junction of two thoroughfare and is denoted by the pairing of the locale-specific thoroughfare names.

The responder determines the nature of the request from the presence or absence of certain parameters. The presence of the address number, for example, should indicate that a request is for a site address, while the presence of a second street name should indicate that a request is for an intersection. Consequently two (intersecting) sets of parameters are specified: SITE_ADDRESS_PARAMETERS and INTERSECTION_ADDRESS_PARAMETERS.


SITE ADDRESS PARAMETERS


INTERSECTION ADDRESS PARAMETERS


Complete Feature Address Parameters

CompleteAddressNumber

Required for Site Address, Forbidden for Intersection Address. This is a string that identifies an address identifier. It is sometimes called the house number or civic number. It should be a series of digits and may be preceded by a series of letters and/or followed by a series of letters. Rural route boxes (and other non-thoroughfare locators, such as latitude-longitude addresses) are not supported by this version. If no alphabetic characters are specified, it may be terminated by a fraction. It must not be present in an intersection request.

CompleteStreetName

Required for Site Address, Required for Intersection Address. This is an string that identifies the full name of the thoroughfare, including directionals, types and qualifiers.

CompleteStreetName2

Forbidden for Site Address, Required for Intersection Address. This is an string that identifies the full name of the intersecting thoroughfare, including directionals, types and qualifiers.

CompleteOccupancyIdentifier

Optional for Site Address, Forbidden for Intersection Address. This is a string that serves as a floor, unit or building identifier within the location identified by the CompleteAddressNumber. This version of the geocoder will accept the string but does not use it.


Place State Zip Parameters

PlaceName

Optional. This is a string that identifies the municipal, town or city name in which the address is located.

StateName

Optional. This is a string that identifies the state, province, or national subdivision in which the place name is located.

ZipCode

Optional. The value for this parameter should be the USPS postal zip code for the address.

ZipPlus4

Optional. This 4 digit number identifies the extension to the zip code and should not be present if the zip code is absent.


Additional Parameters


RequestStrategy

Optional. The default is RequestStrategy=Both - The responder first attempts to match with a precise address. If results are not satisfactory, it abandons the precise results and does an interpolated matching. If the value for this variable is RequestStrategy=Precise the responder returns only the precise results. If the value is RequestStrategy=Interpolated it returns only interpolated results.

InterpolationOffset

Optional. This value must be a decimal number not less than 0.00 and not greater than 100.00. It is interpreted as the number of meters to offset an interpolated address from the street. The default is 5.0. For example, to set the returned coordinates at 10 meters from the road, use InterpolationOffset=10.0.

IntersectionRadius

Optional. This value must be a decimal number not less than 0.00 and not greater than 100.00. It is interpreted as the maximum distance within which two points will snap together to form an intersection. It is interpreted as the radial distance from the center of an intersection such that all points. This parameter allows the user to configure for locales which have large intersections or have short distances between intersections. As a special usage, setting the variable to zero will ensure that all points within the default in an intersection are returned (rather than a single representative point). The default is 30.00 meters.