Geocode POST Request
The POST request enables you to submit a single input address or a list of addresses for batch processing. Matching and/or geocoding preferences can optionally be specified to the Geocode service and receive the associated latitude/longitude coordinates and location information. The preference options for a POST request are the complete set of available options.
Base URI
http://<server>:<port>/rest/GlobalGeocode/geocode[.content type]
Where:
- json
- Default content type is JSON, unless superseded by HTTP content negotiation
- xml
- Default content type is XML, unless superseded by HTTP content negotiation
Request Parameters
- addresses - The address or addresses to be geocoded. Required.
- type - The type of geocode. Optional.
- preferences - The matching and geocoding options. Optional.
- mustMatchMode - The match criteria for determining match candidates Optional.
- returnFieldsDescriptor - Controls the return of additional data on a candidate. Optional.
Address Parameters
>The addresses array of Address objects. The addresses array may contain one or more input addresses. The addresses element is a required element.
Parameter | Type | Description |
---|---|---|
placeName | String | Building name, place name, Point of Interest (POI), company or firm name
associated with the input address. Optional. For example:
Pitney Bowes |
mainAddress | String | Single Line input—If no other field is populated, then the
mainAddress entry will be treated as a single line input and
can be a collection of address field elements. The input order of the address fields
should reflect the normal address formatting for your country. Optional. For
example: 4750 Walnut St., Boulder CO, 80301 Street Address—If the address fields (placeName, lastLine, postalCode, etc.) are provided separately, then the content of this field will be treated as the street address part and can include company name, house number, building names and street names. Optional. Street Intersection Input—To enter an intersection, specify the two street names separated by a double ampersand (&&). |
lastLine | String | The last line of the address. Optional. |
areaName1 | String | Specifies the largest geographic area, typically a state or province. Optional. |
areaName2 | String | Specifies the secondary geographic area, typically a county or district. Optional. |
areaName3 | String | Specifies a city or town name. Optional. |
areaName4 | String | Specifies a city subdivision or locality. Optional. |
postCode1 | String | The postal code in the appropriate format for the country. Optional. |
postCode2 | String | The postal code extension in the appropriate format for the country. Optional. |
country | String | ISO 3166-1 alpha-3 country code. Required. For country codes, see Country Reference Listing and ISO 3166-1 Country Codes. |
addressNumber | String | House or building number. |
streetName | String | Street name. |
unitType | String | Specifies the type of unit, such as Apt., Ste. and Bldg. |
unitValue | String | Specifies the unit value/number, such as "3B". |
Type Parmeters
The type object of type geocodeType has the following parameters. The type parameter is optional.Parameter | Type | Description |
---|---|---|
geocodeType | String |
Indicates the geocode type to be performed. Optional.
|
Preference Parameters
The preferences object of type Preferences consists of the following elements. The elements are only applicable to the Geocode service. The preferences element is optional.
To override the default value of a preferences element for a specific country, specify the key/value pair in the customPreferences object, with the key
constant preceded by the ISO-3166 3-character country code plus a period. For
example: "DEU.fallbackToGeographic
.
Parameter | Type | Description |
---|---|---|
returnAllCandidateInfo | Boolean | Specifies whether to return all available information for each candidate.
|
fallbackToGeographic | Boolean | Specifies whether to attempt to determine a geographic region
centroid when an address-level geocode cannot be determined. Optional.
|
fallbackToPostal | Boolean | Specifies whether to attempt to determine a post code centroid
when an address-level geocode cannot be determined. Optional.
|
FALLBACK_TO_WORLD | String | When XWG is installed, it specifies whether to use the World Geocoder (XWG) to
determine a geocode when either a country geocoder is not installed or a country
geocoder is installed without a geocoding dataset. The World Geocoder (XWG) may
return either a postal or geographic geocode depending on the level of support in
the XWG geocoding dataset. Optional.
|
maxReturnedCandidates | Integer | The maximum number of candidates to return. Optional. Must be an integer value. Default = 1. |
streetOffset | Double | Indicates the offset distance from the street segments to use in street-level
geocoding. The distance is specified in the units you specify in the
streetOffsetUnits option. Default value = 7 meters. The offset distance is used in street-level geocoding to prevent the geocode from being in the middle of a street. It compensates for the fact that street-level geocoding returns a latitude and longitude point in the center of the street where the address is located. Since the building represented by an address is not on the street itself, you do not want the geocode for an address to be a point on the street. Instead, you want the geocode to represent the location of the building which sits next to the street. For example, an offset of 50 feet means that the geocode will represent a point 50 feet back from the center of the street. The distance is calculated perpendicular to the portion of the street segment for the address. Offset is also used to prevent addresses across the street from each other from being given the same point. The following diagram shows an offset point in relation to the original point. |
streetOffsetUnits | String | Specifies the unit of measurement for the street offset. One of the following:
|
cornerOffset | Double | Specifies the distance to offset the street end points in street-level
matching. The distance is specified in the units you specify in the
cornerOffsetUnits option. This value is used to prevent addresses at street corners
from being given the same geocode as the intersection. Defines the offset position
of the geocoded point with respect to the corner. Default value = 7 meters. The following diagram compares the end points of a street to offset end points. |
cornerOffsetUnits | String | Specifies the unit of measurement for the corner offset. One of the following:
|
matchMode | String | Match modes determine the leniency used to make a match between the input
address and the reference data. Select a match mode based on the quality of your
input and your desired output. The following match modes are available:
|
clientCoordSysName | String | Specifies the coordinate system that you want to convert the
geometry to. The format must be the European Petroleum Survey Group (EPSG) code or
the SRID code. Default = EPSG:4326 . Specify the
coordinate reference system in the format
|
customPreferences | Map<String key, String value> | Specifies the country-specific input preferences. This object can be used to
specify:
To override the default value for a specific country, precede the key
constant with the ISO-3166 3-character country code plus a period, and then specify
the value. For example, in an XML request, an entry for a country override would
look as follows:
Custom
country input options are available for the following countries:
For countries that support both custom user dictionaries and standard geocoding datasets, you can set a custom preference with the key KEY_CUSTOM_DICTIONARY_USAGE that will define the searching and matching preferences when both custom and standard dictionaries are available in the geocoding engine. This option is only available with forward geocoding. For more information, see Setting Searching and Matching Preferences When Using Standard and Custom Dictionaries. To locate information on whether your country supports custom user dictionaries, refer to the "Supported Geocoding Datasets" section in the country's write-up. When the World geocoder (XWG) is installed, you can set a custom preference called FALLBACK_TO_WORLD. This preference specifies whether to use XWG to determine a geocode when either a country geocoder is not installed or a country geocoder is installed without a geocoding dataset. XWG may return either a postal or geographic geocode depending on the level of support in the XWG geocoding dataset. Optional.
|
preferredDictionaryOrder | List<String> | Specifies the dictionary search order when multiple dictionaries are installed. The default search order is the order in which the dictionaries are configured. |
mustMatchFields Parameter
mustMatchFields object of type FieldsMatching allows setting the match criteria for determining match candidates. To enable these options, you must set the matchMode field to Custom.
To override the default value of a
mustMatchFields element for a specific country, specify the
key/value pair in the customPreferences object, with the key
constant preceded by the ISO-3166 3-character country code plus a period. For
example: "CAN.matchOnAddressNumber
".
Parameter | Type | Description |
---|---|---|
matchOnAddressNumber | Boolean |
|
matchOnPostCode1 | Boolean |
|
matchOnAreaName1 | Boolean |
|
matchOnAreaName2 | Boolean |
Note: This option is not supported by USA.
|
matchOnAreaName3 | Boolean |
|
matchOnAreaName4 | Boolean |
|
matchOnAllStreetFields | Boolean |
|
mustMatchInput | Boolean |
|
returnFieldsDescriptor
returnFieldsDescriptor object of type returnFieldsDescriptor controls the return of additional data on a candidate. By default, the extended candidate information is not returned, but in the cases where more is available, it can be controlled in the following ways:
To override the default value of a
returnFieldsDescriptor element for a specific country,
specify the key/value pair in the customPreferences object,
with the key constant preceded by the ISO-3166 3-character country code plus a
period. For example: "AUS.returnAllCustomFields
".
Parameter | Type | Description |
---|---|---|
returnAllCustomFields | Boolean |
|
returnedCustomFieldKeys | List<String> | Specifies a list of keys that represent the custom fields to be returned in the
candidate's customFields output. For example:
“CTYST_KEY ” or “DATATYPE ”. Default: empty.Note:
To specify multiple key/value pairs for a country, use spaces to separate the
names of the custom fields to be returned. For example:
"USA.returnedCustomFieldKeys" : "LAT LON SHORT_CITY" .
Candidates which have this information available will include the three custom
fields with these keys in the candidate's customFields
output.Note: Custom fields vary by country. To locate your country's
information, refer to Country-Specific Information to find the corresponding section in the
appendix that provides more details.
|
returnMatchDescriptor | Boolean |
|
returnStreetAddressFields | Boolean |
|
returnUnitInformation | Boolean |
|