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>/<context>/rest/GeocodeService/<name_of_service>

See Example: JSON POST Request & Response.

http://<server>:<port>/rest/GlobalGeocode/geocode[.content type]

Request Parameters

The POST request comprises the following input parameters:

addresses - The address or addresses to be geocoded. The addresses array of Address objects. The addresses array may contain one or more input addresses. Required.
type - The type of geocode. Optional. The type parameter is 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.


Parameter	Type	Description
POST: type GET: 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.
POST: 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.
POST: fallbackToGeographic GET: fallbackGeo	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.
POST: fallbackToPostal GET: fallbackPostal	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.
POST: maxReturnedCandidates GET: maxCands	Integer	The maximum number of candidates to return. Optional. Must be an integer value. Default = 1.
streetOffset	Double	The offset distance from the street segments. The distance is in the units you specify in the streetOffsetUnits preference. 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. 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.
streetOffsetUnits	String	Unit of measurement for the street offset. One of the following: Feet, Meters (default).
cornerOffset	Double	Distance to offset the street end points in street-level matching. The distance is in the units you specify in the cornerOffsetUnits preference. 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	Unit of measurement for the street 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. 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. 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.
maxRanges	Integer	A range is a series of addresses along a street segment. For example, 5400-5499 Main St. is an address range representing addresses in the 5400 block of Main St. A range may represent just odd or even addresses within a segment, or both odd and even addresses. A range may also represent a single building with multiple units, such as an apartment building. This option specifies the maximum number of ranges to return for each candidate. Since the geocoder returns one candidate per segment, and since a segment may contain multiple ranges, this option allows you to see the other ranges in a candidate's segment. Must be an integer value. Default = 0.
maxRangeUnits	Integer	This option specifies the maximum number of units (for example, apartments or suites) to return for each range. For example, if you were to geocode an office building at 65 Main St. containing four suites, there would be a maximum of four units returned for the building's range: 65 Suite 1, 65 Suite 2, 65 Suite 3, and 65 Suite 4. If you were to specify a maximum number of units as 2, then only two units would be returned instead of all four. Must be an integer value. Default = 0.
POST: 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`.
POST: 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.
POST: 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.
POST: matchOnPostCode2	Boolean	true A match must be made to the input PostCode2 field. false A match does not need to be made to the input PostCode2 field. Default.
POST: 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.
POST: 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.
POST: 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.
POST: 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.
POST: 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.
POST: returnAllCustomFields	Boolean	true Return all of the custom fields for the candidate. false Return only the standard set of fields for the candidate. Default.
POST: returnedCustomFieldKeys	List<String>	Specifies a list of keys that represent the custom fields to be returned in the candidate's customFields output. To specify multiple key/value pairs for a country, use spaces to separate the names of the custom fields to be returned. Custom fields vary by country. For example: “`CTYST_KEY`” or “`DATATYPE`”. Default: empty.
POST: 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.
POST: returnStreetAddressFields	Boolean	true Return all of the individual street fields that make up the formattedStreetAddress field separately, as follows: MAIN_ADDRESS THOROUGHFARE_TYPE ADDRESS_ID PRE_ADDRESS POST_ADDRESS PRE_DIRECTIONAL POST_DIRECTIONAL false Do not return the individual street fields separately; return these values in the formattedStreetAddress field. Default.
POST: 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.