Geo Addressing API Objects

This list includes both request and response objects.

AddressMatch

Response Element Type Description
type

MatchType

ADDRESS, STREET, ADMIN, POBOX, POI*, NOMATCH, UNKNOWN

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

description <MatchDescription> Array Indicates the level of matching.

EXACT or NONE

AddressRequest

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

AddressResponse

Response Element Type Description
status Status Status of the response, see Status Codes (Addressing API) for an explanation of all codes.
results <Result> array List of candidates.

AdminField

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

Capabilities

Element Type Description
features < Feature> array Type of geocoding service operation. One of the following:
  • geocode
  • reverseGeocode
  • interactive
  • keyLookup
countries Map<String, CountryField> Supported countries
descriptions <FeatureDescription> array Feature description, contains information for supported features.
additionalFields <DataField> array List of all additional fields from all features or datasets.

CountryField

Response Element Type Description
name String Common name of the country. For a complete listing of all codes, see Country Codes.
isoAlpha2Code String Alphabetic code (alpha-2).

"GB"
isoAlpha3Code String Alphabetic code (alpha-3).

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

"826"

DataField

Field Type Description
name String Name of the field
type String Type of the data field if known. Possible types:
  • string
  • number
  • integer
  • boolean
  • array
  • object

Distance

Field Type Description
value double Distance of the radius in which to search for a match. Default is 5
distanceUnit string

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

Explanation

Response Element Type Description
identifier String An ID generated from the underlying source reference data of an address.
addressMatch AddressMatch Describes the quality of address matching based on the user input address.
source Object 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 Object Ability to map a feature to an address processor, based on specified label. For example , map geocoding to one address processor and address verification to another address processor. 
Example
"factoryDescription": {
"label": "ggs",
"featureSpecific": {
"VERIFY": "global_locator"
}
}

Features include:

"GEOCODE"
"PARSE"
"VERIFY"
"REVERSE_GEOCODE"
"INTERACTIVE"
"LOOKUP"

Feature

Field Type Description
Feature object

Features include:

"GEOCODE"
"PARSE"
"VERIFY"
"REVERSE_GEOCODE"
"INTERACTIVE"
"LOOKUP"

FeatureDescription

Field Type Description
features <Feature> array List of supported features
countries <String> array List of countries
additionalFields <DataField> array List of additional fields

GeocodeRequest

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

GeocodeResponse

Response Element Type Description
responses <Response> array List containing responses for each address request.

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

KeyValue

Field Type Description
key String Name of the Key such as PBKEY.
value String Value for the given Key such as “P00003PZZOIE”.

Location

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

LocationExplanation

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 Object Any additional metadata about the location

LocationType

Field Type Description
LocationType Object LocationType describes the Geometry location. For example, it will tell the user what the precision of the returned Location is or how it was determined. For more information, see Location codes (Addressing API).

LookupRequest

Field Type Description
type LookupType

LookupType controls what type of information will be requested. For example,

  • "PB_KEY" for USA data
  • "GNAF_PID for AUS G-NAF data
preferences Preferences Set options such as the number of results to return (maxResults).
keys <LookupRequestValues> array List of keys to be processed.

LookupRequestValues

Field Type Description
type LookupType This is same as LookupRequest.type. It allows it to override if user want to control per key what type of lookup they want to perform, when using a batch request.
keyValues <KeyValue> array A list of unique identifiers for the address.

LookupType

Field Type Description
LookupType Object The type of key for a lookup:
  • "PB_KEY" for USA data
  • "GNAF_PID for AUS G-NAF data

MatchDescription

Field Type Description
label String For example, streetName
matchType String EXACT, PARTIAL, ALIAS_EXACT, ALIAS_PARTIAL, ADDED, REMOVED, NONE
returnType String INPUT, PREFERRED, ALIAS, PARTIAL, NONE
matchedSubstring String For the Predict service, returns the portion of the input that matched against the output.

MatchType

Field Type Description
MatchType Object

Describes the level of address match. Possible values:

  • ADDRESS
  • STREET
  • ADMIN
  • POBOX
  • POI
  • NOMATCH

ParsedAddress

Response Element Type Description
score Integer

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
from String Field label from the request, if available. For example, the value was parsed from the admin1 field or from Address Line 1, etc.
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

ParseRequest

Field Type Description
preferences Preferences Set options such as the number of results to return (maxResults).
address RequestAddress List of addresses to be processed.

ParsedResponse

Field Type Description
errorMessage String Exception message. Returns the message returned from the underlying exception.
status Status Status of the response, see Status Codes (Addressing API) for an explanation of all codes.
parsed <ParsedAddress> Array List of parsed address components

Point

Field Type Description
Point Object A specific position represented by a latitude and longitude coordinate.

Position

Field Type Description
y Double

Latitude in degrees. For example: 43.643469
x Double

Longitude in degrees. For example: -79.391165

PredictionResponse

Field Type Description
status Status Status of the response, see Status Codes (Addressing API) for an explanation of all codes.
predictions <PredictionResult> array List of results
errorMessage String

Exception message. Returns the message returned from the underlying exception.

PredictionResult

Field Type Description
prediction 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"
distance Distance Displays the defined search radius. The default is 5 meters.
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 Displays the components of the address.
addressLines <String> array 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",
"UNITED KINGDOM"
location Location Describes the location type and coordinates.
parsed <ParsedAddresss> array Shows how the address was parsed, using the specified addressing process.
explanation Explanation Describes the level of matching for each component of an address.
customFields object Returns additional information about the address; see Custom Output Fields (All Fields).

PredictRequest

Parameter Type Description
preferences Preferences Set options such as the number of results to return (maxResults).
address RequestAddress Request address that will be processed.

Preferences

Option Type Description
distance Distance Define the search radius. The default is 5 meters.
customPreferences

Object

 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 service-specific information: Verify , Geocode, Predict, or Reverse. (Currently, the Lookup and Parse services do not have any custom preferences.)
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.
returnOfAdditionalFields <String> array

This lets the user control which additional fields they want to have returned if they do not want to return all info.

For example, to return the PreciselyID, use the value PB_KEY
{
  "preferences" : {
    "returnOfAdditionalFields " : ["PB_KEY"]
  }
}
factoryDescription FactoryDescription Controls which address processor will process the request.
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.
streetOffset

Distance

Specify the offset distance from the street segments to use in street-level geocoding. The offset prevents the geocode from being in the middle of a street.
originXY <Double> array XY coordinates of the origin address. 
{
"preferences" : 
  {
  "originXY" : [-73.70252500000001, 42.68323]
    },
  "address" : 
  {
  "mainAddressLine" : "350 Jordan Rd"
  }
}
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.
clientLocale Object Specify the locale value. For example, specify "th" for the Thai language.
cornerOffset

Distance

Specify the distance to offset the street end points in street-level matching. This 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. The default is 7 meters.
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.
maxResults Integer The maximum number of candidates to return. Default = 1.
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.
Note:
For the list of MustMatch fields for custom preference, see, Custom Preferences Geocode Service.
type String

Indicates the geocode type to be performed.

ADDRESS
Geocode to a street address. Default.
GEOGRAPHIC
Geocode to the geographic centroid of a city or state.
POSTAL
Geocode to a postal code.

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.).

Response

Field Type Description
errorMessage String Exception message. Returns the message returned from the underlying exception.
status Status Status of the response, see Status Codes (Addressing API) for an explanation of all codes.
results <Result> array List of results based on the specified criteria.

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 CountryField 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".

The field can contain either longName or shortName.

Note:
Only a few countries support shortName. In most cases, shortName and longName will have the same value.
admin2 AdminField Specifies the secondary geographic area, typically a county or district.

"Douglas County" or "West Mumbai".

The field can contain either longName or shortName.

Note:
Only a few countries support shortName. In most cases, shortName and longName will have the same value.
city AdminField Specifies a city or town name.

"New York City"
neighborhood AdminField Specifies a city subdivision or locality.

""
suburb AdminField Mixed-use or residential area within commuting distance of a city or urban area.

""
subdivision code String Refers to the ISO 3166-2 code, which is the international standard for identifying the main subdivisions of countries, such as states, provinces, or regions.
Format: CC-XXX
  • CC = the country’s ISO 3166-1 alpha-2 code (two letters)
  • XXX = up to three alphanumeric characters representing the subdivision. This value is determined by the AreaName1 field from the response object. If AreaName1 is missing, the subdivision code may not be available. The length and format of XXX can vary by country, depending on how AreaName1 is represented.
Examples:
  • US-CA → California, United States
  • IN-MH → Maharashtra, India
borough AdminField Unit of local government or other administrative subdivision.

"Vazira" or "Manhattan"
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 Displays components of the address
addressLines <String> array 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",
"UNITED KINGDOM"
location Location

Describes the location type and coordinates.
parsed ParsedAddress

Shows how the address was parsed, using the specified addressing process.
explanation Explanation Describes the level of matching for each component of an address.
customFields Object

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

ReverseRequest

Response Element Type Description
preferences Preferences Set options such as the number of results to return (maxResults).
feature SimpleFeature SimpleFeature object with geometry and additional properties.

SimpleFeature

Response Element Type Description
type String Feature
properties Object 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.

VerifyRequest

Parameter Type Description
preferences Preferences Set options such as the number of results to return (maxResults).
address RequestAddress List of addresses to be processed.

VerifyResponse

Parameter Type Description
responses

<Response> array

 List of results based on the criteria specified in the request.