Addressing API Objects

This list includes both request and response objects.

Objects are used by:

Verify Service: Request or Response

Geocode Service: Request or Response

AddressMatch

Response Element Type Description
type Enum ADDRESS, STREET, ADMIN, POBOX, POI*, NOMATCH, UNKNOWN

*To return POI values, configure a dataset that contains points of interest (POI) data

description <Description> Array Indicates the level of matching.

EXACT or NONE

AddressRequest

Parameter Type Description
addresses <Address> Array List of addresses to be processed.
preferences Preferences Set options such as the number of results to return (maxResults).

AddressResponse

Response Element Type Description
status String Status of a request.

OK, ZERO_RESULTS, UNKNOWN_ERROR, INVALID_CONFIGURATION, INVALID_REQUEST, DATA_NOT_LICENSED
results <Result> array List of candidates.

AdminField

Element Type Description
longName String "New York" or "Maharashtra"
shortName String "NY"

Country

Response Element Type Description
isoAlpha2Code String Alphabetic code (alpha-2).

"GB"

isoAlpha3Code String Alphabetic code (alpha-3).

"GBR"
isoNumericCode Number Numeric code (numeric-3).

"826"
name String Common name of the country.

Description

Response Element Type Description
label String For example, streetName
matchType Enum EXACT, PARTIAL, ALIAS_EXACT, ALIAS_PARTIAL, ADDED, REMOVED, NONE
returnType Enum INPUT, PREFERRED, ALIAS, PARTIAL, NONE

Explanation

Response Element Type Description
addressMatch AddressMatch Describes the quality of address matching based on the user input address.
identifier String An ID generated from the underlying source reference data of an address.
locationMatch LocationMatch Location precision.
source Map <string, string> Returns information about the address processor. Values are: "ggs" , "global_locator" , or "finalist".
Note: "finalist" only processes USA data and input must be in multiline

FactoryDescription

Parameter Type Description
label string Sets the addressing processor based on the configured data. Labels are case-sensitive and must be lowercase. Default is "". If you have configured data for multiple products, the default processing order is as follows:
ggs
Available for the whole world.
global_locator
Available for the whole world.
finalist
Only processes USA data and input must be in multiline format.
featureSpecific Feature, string

Feature

Response Element Type Description
type String Feature
properties <string,string> crsName - The coordinate reference system (CRS) used for the candidate's geocode. Expressed in epsg:nnnn format; the default is epsg:4326.
geometry Geometry Provides the candidate's geometry type and coordinates.

Geometry

Response Element Type Description
type String Geometry type. The return value is always Point.
coordinates < number (double) > array The candidate's geocode, specified as x (longitude) and y (latitiude) coordinates separated by a comma.
149.19290021000003,
-31.276491389162288

Location

Response Element Type Description
explanation LocationExplanation Provides location quality and precision.
feature Feature "Feature" object with geometry and additional properties.

LocationExplanation

Note: this object is not in the Verify Service.
Response Element Type Description
type String ADDRESS_POINT, STREET, or CITY
designation String When the location type is STREET or CITY, designation returns CENTROID.

LocationMatch

Note: this object is not in the Verify Service.
Response Element Type Description
description LocationType BUILDING, BUILDING_CENTROID, ROOM, ROOM_CENTROID, UNIT, UNIT_CENTROID, PARCEL, PARCEL_CENTROID, ENTRANCE, CENTER_LINE_PROJECTED, POI, IOT_DEVICE, SEGMENT_CENTER, UNKNOWN
type LocationType ADDRESS_POINT, ADDRESS_INTERPOLATED, INTERSECTION, NEAR_BY_ADDRESS, STREET_CENTER, STREET_BLOCK, POSTAL_CENTROID, NEIGHBORHOOD_CENTROID, CITY_CENTROID, ADMIN2_CENTROID, ADMIN1_CENTROID, COUNTRY_CENTROID, NO_LOCATION, UNKNOWN
designation LocationType Placement of the location. For example, when the location type is STREET or CITY, designation returns CENTROID.
additionalMetadata Map<String, String> Any additional metadata about the location

ParsedAddress

Response Element Type Description
[label] String Parsed.[label] indicates the address processor used for parsing.
score Number

Indicates how well the address was parsed. Currently, returns a "0".

classifications <ParsedFieldClassification> array Displays the parsed components of an address using the specified address processor.

ParsedFieldClassification

Response Element Type Description
label String Parsed component of an address such as street, admin1, city, addressNumber, postalCode, and streetSuffix.
value String The value for that portion of the parsed address
start Integer Placeholder for future functionality
end Integer Placeholder for future functionality

Preferences

Option Type Description

maxResults

 Integer The maximum number of candidates to return. Optional. Default = 1.

returnAllInfo

 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.
factoryDescription factoryDescription Controls which address processor will process the request.
clientLocale string Specify the locale value. For example, specify "th" for the Thai language.
distance.distanceUnit string

Unit of measurement for the search radius: FOOT, METER, MILE, KILOMETER. Default is METER (case-sensitive).

Note: Prior to GG SDK 4.0, this was FEET, METERS, MILES, KILOMETERS with a default of METERS.
distance.value number Distance of the radius in which to search for a match. Default is 5
streetOffset.distanceUnit string Unit of measurement for the street offset: FOOT, METER, MILE, KILOMETER. Default is METER (case-sensitive).
streetOffset.value number Distance of the street offset.
cornerOffset.distanceUnit string Unit of measurement for the corner offset: FOOT, METER, MILE, KILOMETER. Default is METER (case-sensitive).
cornerOffset.value number Distance to offset the street end points in street-level matching. The distance is in the units you specify in the cornerOffset.distanceUnit 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.
customPreferences

Map<String key, String value>

 For use against any country dataset, define custom preferences to control additional functionality such as matching criteria, address casing, and enable functionality like DPV and SuiteLink. See Addressing API Custom Preferences.

RequestAddress

Parameter Type Description
addressLines List Requested address, based on the country's addressing standard.

Single-line request:

"10 downing street london SW1A 2AA"
Multi-line request:
"10 DOWNING STREET",
"LONDON",
"SW1A 2AA"
country String Values are based on the ISO 3166-1 standard for country codes (returned in alpha-2, alpha-3, or numeric format).
addressNumber String House or building number.

"10" or "630"
admin1 String The largest geographic area, typically a state or province.

"New York" or "Maharashtra".

admin2 String The secondary geographic area, typically a county or district.

"Douglas County" or "West Mumbai".
city String Specifies a city or town name.

"New York City"
borough String Unit of local government or other administrative subdivision.

"Vazira" or "Manhattan"
neighborhood String A city subdivision or locality.

"Highlands Ranch"
suburb String Mixed-use or residential area within commuting distance of a city or urban area.
postalCode String Main postal code.

"80125"
postalCodeExt String Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012.

"8012"
placeName String If applicable, indicates the name of the candidate's place or building.

"PRIME MINISTER& FIRST LORD OF THE TREASURY"
building String A roofed and walled structure built for permanent use.
floor String Each level within a building.
room String A single room within a building.
unit String The unit number, such as "3B".
unitType String A group or suite of rooms within a building that are under common ownership or tenancy, typically having a common entrance. (APT, STE, FLAT, etc.).

ResponseAddress

Response Element Type Description
formattedAddress String All components of the address, formatted to the country's standard, on one line.
"PRIME MINISTER& FIRST LORD OF THE TREASURY, 10 DOWNING STREET, LONDON, SW1A 2AA"

or "630 168TH ST, NEW YORK NY 10032-3725"
formattedStreetAddress String Street portion of the address, including the directional and street suffix, formatted to the country's standard.

"10 DOWNING STREET" or "630 W 168TH ST"
formattedLocationAddress String Location portion of the address, formatted to the country's standard.

"LONDON SW1A 2AA" or "NEW YORK, NY 10032-3725"
addressNumber String House or building number.

"10" or "630"
country Country Values are based on the ISO 3166-1 standard for country codes (returned in alpha-2, alpha-3, or numeric format).
admin1 AdminField Specifies the largest geographic area, typically a state or province.

"New York" or "Maharashtra".

admin2 AdminField Specifies the secondary geographic area, typically a county or district.

"Douglas County" or "West Mumbai".
city AdminField Specifies a city or town name.

"New York City"
borough AdminField Unit of local government or other administrative subdivision.

"Vazira" or "Manhattan"
neighborhood AdminField Specifies a city subdivision or locality.

""
postalCode String Main postal code.

"80125"
postalCodeExt String Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012.

"8012"
placeName String If applicable, indicates the name of the candidate's place or building.

"PRIME MINISTER& FIRST LORD OF THE TREASURY"
building String A roofed and walled structure built for permanent use.
floor String Each level within a building.
room String A single room within a building.
unit String The unit number, such as "3B".
unitType String A group or suite of rooms within a building that are under common ownership or tenancy, typically having a common entrance. (APT, STE, FLAT, etc.).
street String Street name only (no directional or street suffix).

"FRASER RIVER" or "168TH"

Result

Response Element Type Description
score Integer Provides a number from 0-100 to indicate how much the input was changed in order to match to the output candidate. It looks at certain fields including the house and unit numbers, street name, directional, and type, as well as postcode and area name fields. A score of 100 means that all the input fields checked exactly matched the output candidate. Available for all countries and the calculation is consistent from one country to another.
address ResponseAddress
addressLines List Displays multiple formatted lines to support the postal standard of a given country.
"PRIME MINISTER& FIRST LORD OF THE TREASURY",
"10 DOWNING STREET",
"LONDON",
"SW1A 2AA"
location Location

Describes the location type and coordinates.
parsed ParsedAddress

Shows how the address was parsed, using the specified addressing process.
explanation AddressMatch Describes the level of matching for each component of an address.
customFields Map <string, string>

Returns additional information about the address; see Custom Output Fields (All Fields).