Preferences - geo_addressing_sdk - 5.0

Geo Addressing SDK Developer Guide

Product type
Software
Portfolio
Locate
Product family
Geo Addressing
Product
Geo Addressing SDK
Version
5.0
Language
English
Product name
Geo Addressing SDK
Title
Geo Addressing SDK Developer Guide
Copyright
2023
First publish date
2007
ft:lastEdition
2024-07-12
ft:lastPublication
2024-07-12T13:44:57.839102

Preferences supported by the Geocode Service include a variety of settings for match mode, geocoding to a street or administrative area, fallback to a less specific location if an exact match cannot be found, and more. The following table describes the preferences available to all countries, and notes when a preference does not apply to a country. Custom preferences for all countries are explained in Custom Preferences: Geocode Service (Geocoding API).

Note: Some parameters are identified with POST and GET. Those with both indicate a difference in the parameter name. The parameters with no POST and GET are used for either request type using the same parameter name. Other parameters are either POST or GET as marked.
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.