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:

[.content type] indicates that the specified content type will be used by default. Optional.
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

The POST request comprises the following input 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.
These objects and their elements are defined in the following table.

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
4750 Walnut St.
Boulder, CO 80301

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.

Address
Geocode to a street address. Default.
Geographic
Geocode to the geographic centroid of a city or state.
Postal
Geocode to a postal code.

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.
True
Return all available information for each candidate.
False
Do not return all available information for each candidate. Default.
fallbackToGeographic Boolean Specifies whether to attempt to determine a geographic region centroid when an address-level geocode cannot be determined. Optional.
True
Return a geographic centroid when an address-level centroid cannot be determined. Default.
False
Do not return a geographic centroid when an address-level centroid cannot be determined.
fallbackToPostal Boolean Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional.
True
Return a post code centroid when an address-level centroid cannot be determined. Default.
False
Do not return a post code centroid when an address-level centroid cannot be determined.
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.
True
Use the World Geocoder (XWG) for matching when either a country geocoder is not installed or a country geocoder is installed without a geocoding dataset.
False
Do not use the World Geocoder (XWG) for matching when either a country geocoder is not installed or a country geocoder is installed without a geocoding dataset. Default.
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:
  • Feet
  • Meters - Default
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:
  • Feet
  • Meters - Default
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:
Exact
Requires a very tight match. This restrictive mode generates the fewest match candidates, which decreases the processing time. When using this mode, ensure that your input is very clean; free of misspellings and incomplete addresses.
Standard
Requires a close match and generates a moderate number of match candidates. Default.
Relaxed
Allows a loose match and generates the most match candidates, which increases the processing time and results in more multiple matches. Use this mode if you are not confident that your input is clean; free of misspellings and incomplete addresses.
Custom
Provides the capability for you to define the matching criteria by setting MustMatch fields; however, you can only set the MustMatch fields using a POST request. For a GET request, the MustMatch default values are used. For more information on the MustMatch fields, refer to mustMatchFields.
Interactive (USA only)
Available in single-line address matching only. This mode is designed to better handle the specific matching challenges presented by interactive matching. Interactive mode permits for more flexible matching patterns and may, in some cases, return additional possible matches than relaxed match mode.
CASS (USA only)
Imposes additional rules to ensure compliance with the USPS CASS regulations. The purpose of this match mode is to create mailable addresses for USPS mailing discounts. Use this mode to standardize your input for mailing. This mode generates a large number of match candidates.
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 codespace:code.

customPreferences Map<String key, String value> Specifies the country-specific input preferences. This object can be used to specify:
  • A country override to a default value of one or more elements in the preferences, mustMatchFields or returnFieldsDescriptor objects.
  • A custom country input option.
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:
<customPreferences>
 <entry>
  <key>USA.maxReturnedCandidates</key>
  <value>3</value>
 </entry>
</customPreferences>
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.

True
Use the World Geocoder (XWG) for matching when either a country geocoder is not installed or a country geocoder is installed without a geocoding dataset.
False
Do not use the World Geocoder (XWG) for matching when either a country geocoder is not installed or a country geocoder is installed without a geocoding dataset. Default.
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
True
A match must be made to the input address number.
False
A match does not need to be made to the input address number. Default.
matchOnPostCode1 Boolean
True
A match must be made to the input PostCode1 field.
False
A match does not need to be made to the input PostCode1 field. Default.
matchOnAreaName1 Boolean
True
A match must be made to the input AreaName1 field.
False
A match does not need to be made to the input AreaName1 field. Default.
matchOnAreaName2 Boolean
True
A match must be made to the input AreaName2 field.
False
A match does not need to be made to the input AreaName2 field. Default.
Note: This option is not supported by USA.
matchOnAreaName3 Boolean
True
A match must be made to the input AreaName3 field.
False
A match does not need to be made to the input AreaName3 field. Default.
matchOnAreaName4 Boolean
True
A match must be made to the input AreaName4 field.
False
A match does not need to be made to the input AreaName4 field. Default.
matchOnAllStreetFields Boolean
True
A match must be made to the input street name, type and directional fields.
False
A match does not need to be made to the input street name, type and directional fields. Default.
mustMatchInput Boolean
True
The other must match fields are ignored and any of the possible input fields provided (postal code, area names, etc.) must match against the candidate for the candidate to be returned.
False
The other must match fields are honored. A match does not need to be made to any specific input field provided for the candidate to be returned. Default.

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
True
Return all of the custom fields for the candidate.
False
Return only the standard set of fields for the candidate. Default.
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
True
Return the match descriptor object, which indicates the parts of the candidate that matched the input address.
False
Do not return the match descriptor object. Default.
returnStreetAddressFields Boolean
True
Return all of the individual street fields that make up the formattedStreetAddress field separately, as follows:
  • MAIN_ADDRESS — the base part of the street name. For example: “River” in “13 River Ave”
  • THOROUGHFARE_TYPE — the thoroughfare type, which may appear before or after the street name, such as Ave, Via, St, Rd, etc.
  • ADDRESS_ID — the unique identifier for the address in the source data
  • PRE_ADDRESS — value may contain articles, etc. that appear before the main street name. For example: “de la” from “Calle de la mesa”
  • POST_ADDRESS — value may contain phrases that appear after the main street name. For example: “de la tiedra” from “Calle Ramon Perez de la tiedra”
  • PRE_DIRECTIONAL — value contains a directional that appears before the main street name. For example: “South” in “123 South Main St”
  • POST_DIRECTIONAL — value contains a directional that appears after the main street name. For example: “SW” in “123 River St SW”
False
Do not return the individual street fields separately; return these values in the formattedStreetAddress field. Default.
returnUnitInformation Boolean
True
Where available, return unit type and unit value information separately in the unitType and unitValue fields, as well as in the formattedStreetAddress field.
False
Where available, return unit type and unit value information only in the formattedStreetAddress field. Default.