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.
The geocoder is invoked by submitting a PARAMETER_STRING as an HTTP POST or GET request to:
HOST_URL/geocode_response.exeThe 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_STRINGThe 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.
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.
methodName=GeocodeRequest&Version=1.1&CompleteAddressNumber=1234&CompleteStreetName=W+Main+St&PlaceName=AnywhereThe General Request Parameters must or may appear in any request, regardless of the kind of request.
Required. All requests must include a value for the methodName
variable. This value describes the type of request being made.
Currently accepted values are:
methodName=GeocodeRequestThe 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.
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:
Version=1.1Required. 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
CountryCode=USOptional 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
RequestID=12345ABCOptional 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
maximumResponses=3Optional All requests may include a value for the
parameter ResponseFormat. Currently accepted values:
ResponseFormat=XMLResponseFormat=JSONResponseFormat=CSVThere are two types of GeocodeRequest supported by this responder:
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.
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.
InterpolationOffset
variable. RequestStrategy
variable.
InterpolationRadius
variable. 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.
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.
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.
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.
Optional. This is a string that identifies the municipal, town or city name in which the address is located.
Optional. This is a string that identifies the state, province, or national subdivision in which the place name is located.
Optional. The value for this parameter should be the USPS postal zip code for the address.
Optional. This 4 digit number identifies the extension to the zip code and should not be present if the zip code is absent.
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.
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.
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.