The Geocode Request

The geocode request is sent as an urlencoded string via HTTP POST or GET. The content type must be application/x-www-form-urlencoded.

Urlencoding is the creation of a query string by taking a number of name-value pairs, concatenating them with ampersands. Spaces are replaced by pluses and non-alphanumeric characters are represented by a percentage sign followed by the hexadecimal value of the character. A html form, such as the one below, uses this method to submit the user's data to the processing program. A form and a browser, however, are not necessary to submit the data - any program that can access the internet can send the data and receive the response. It is only necessary to observe the protocols.

Filling out the following form will post a geocode request to the geocoder.

RequestID

The following field is an optional field that may contain up to 256 characters of content.

RequestID :

maximumResponses

The following optional field specifies the maximum number of candidates you would like returned. If not specified, the default of 30 is used. If specified it must be a positive integer not less than 1 and not more than 100.

maximumResponses :

ResponseFormat

The following field specifies the format of the response and must be one of XML (default), JSON or CSV (Comma-separated values). It is a required element. ResponseFormat:

XML

JSON

CSV

methodName

The following field specifies the method of the request. The only current valid content is "GeocodeRequest". It is a required element.

methodName :

Version

The following field specifies the geocoder interface version. The only current valid content is "1.1". It is a required element.

Version :

CountryCode

The following field specifies the nation. It is a required element. However, with the current datasets, the content is ignored.

CountryCode :

RequestStrategy

The following field specifies the strategy in matching the reference candidates against the query. If BOTH the responder first attempts a PRECISE match, and if scores are not high enough, will then attempt INTERPOLATED. If PRECISE it does PRECISE only. If INTERPOLATED it does INTERPOLATED only. It is optional (BOTH is default) and of relevance only in SITE queries.

RequestStrategy:

BOTH

PRECISE

INTERPOLATED

Interpolation Offset

The following optional field allows the user to modify the default offset from the road used to position an interpolated address. To override the default of 5 meters, specify the number of meters desired. The number should be given as a floating point value not less than 0.00 and not more than 100.00.

InterpolationOffset :

IntersectionRadius

The following optional field allows the user to modify the default distance that will snap together two arc endpoints into an intersection. To override the default of 30.00 meters, specify the number of meters desired. This number should be given as a floating point value not less than 0.00 and not more than 100.00.

IntersectionRadius :

CompleteAddressNumber

The following field specifies the address number. It is a required element for address queries and must be absent for intersection queries. The content cannot be longer than 256 characters in length.

CompleteAddressNumber :

CompleteStreetName

The following field specifies the street name. It is a required element for all queries. The content cannot be longer than 256 characters in length.

CompleteStreetName :

CompleteStreetName2

The following field specifies a second street name. It is a required element for intersection queries but must be absent for address queries. The content cannot be longer than 256 characters in length.

CompleteStreetName2 :

PlaceName

The following field specifies the city. It may be absent if a zipcode is present. The content cannot be longer than 256 characters in length.

PlaceName :

StateName

The following field specifies the state. It is an optional element. Abbreviations are permissable.

StateName :

ZipCode

The following field specifies the 5 digit zip code. It may be absent if a PlaceName is present. It should be a series of exactly 5 digits.

ZipCode :

ZipPlus4

The following field specifies the 4 digit zip code extension. It is an optional element, but is ignored if it is given and the ZipCode is not. It should be a series of exactly 4 digits.

ZipPlus4 :