Response Description

A request to the Geocode service returns a GeocodeServiceResponse object that contains:
  • totalPossibleCandidates— the total number of possible candidates.
  • totalMatches— the total number of matches.
  • candidates — lists one or more candidates that matched to your input address/addresses. Matching and location information is returned for each match candidate.
Response Element Description
totalPossibleCandidates (Integer) Indicates the total number of possible candidates.
totalMatches (Integer) Indicates the total number of matches.
candidates object of type Candidate, consisting of an array with one or more match candidates and associated address, matching and location information. Contains the following elements:
precisionLevel (Integer) A code describing the precision of the geocode. One of the following:
0
No coordinate information is available for this candidate address.
1
Interpolated street address.
2
Street segment midpoint.
3
Postal code 1 centroid.
4
Partial postal code 2 centroid.
5
Postal code 2 centroid.
6
Intersection.
7
Point of interest. (If database contains POI data.)
8
State/province centroid.
9
County centroid.
10
City centroid.
11
Locality centroid.
12-15
Reserved for unspecified custom items.
16
The result is an address point.
17
The result was generated by using address point data to modify the candidate's segment data.
18
The result is an address point that was projected using the centerline offset feature. You must have both a point and a street range database to use the centerline offset feature.
formattedStreetAddress (String)

The formatted main address line.
formattedLocationAddress (String) The formatted last address line.
identifier (String) For street- or point-level candidates, this is usually the segment ID.
precisionCode (String) A code describing the precision of the geocode.

The format of the geocode result string is match_category[additional_match_information].

The possible match categories are as follows:

Z1
Postal match with post code 1 centroid.
Z2
Postal match with partial post code 2 centroid.
Z3
Postal match with post code 2 centroid.
G1
Geographic match with area name 1 centroid.
G2
Geographic match with area name 2 centroid.
G3
Geographic match with area name 3 centroid.
G4
Geographic match with area name 4 centroid.

The matches in the 'S' category indicate that the record was matched to a single address candidate.

SX
Point located at a street intersection.
SC
Match point located at the house-level that has been projected from the nearest segment.
S0
No coordinates are available, but parts of the address may have matched the source data.
S4
The geocode is located at a street centroid.
S5
The geocode is located at a street address.
S7
The geocode is located at a street address that has been interpolated between point house locations.
S8
Match point located at the house location.
PO Box candidates return a result code beginning with the letter B.
B1
B1 results are matched to unvalidated PO Box number.
B2
B2 results are matched to a range of PO Boxes.
Additional match information is of the format HPNTSCSZA. If a match result was not made for the specified component, a dash (-) will appear in place of a letter.
H
House number.
P
Street prefix direction.
N
Street name.
T
Street type.
S
Street suffix direction.
C
Town name.
Z
Post code.
A
Geocode dataset.
U
Custom User Dictionary.
For more information, see Global Result Codes.
DPV_CMRA Indicates whether the address is for a Commercial Mail Receiving Agent:
Y
Yes, the address is a CMRA.
N
No, the address is not a CMRA.
DPV_CONFIRM Indicates if a match occurred for DPV data:
N
Nothing confirmed.
Y
Everything confirmed (ZIP+4, primary and secondary).
S
ZIP+4 and primary (house number) confirmed.
D
ZIP+4 and primary (house number) confirmed and a default match, secondary did not confirm.
DPV_FALSE_POS DPV false-positive indicator:
Y
False-positive match found.
DPV_FOOTNOTE1 Information about the matched DPV records:
AA
ZIP+4 matched.
A1
Failure to match a ZIP+4.
DPV_FOOTNOTE2
BB
All DPV categories matched.
CC
DPV matched primary/house number, where the secondary/unit number did not match (present but invalid).
M1
Missing primary/house number.
M3
Invalid primary/house number.
N1
DPV matched primary/house number, with a missing secondary number.
P1
Missing PS, RR, or HC Box number.
P3
Invalid PS, RR or HC Box number.
F1
All military addresses.
G1
All general delivery addresses.
U1
All unique ZIP Code addresses.
DPV_FOOTNOTE3
R1
Matched CMRA, without a present secondary/unit number.
R2
Matched CMRA.
Note: A unique ZIP Code is a ZIP Code assigned to a company, agency, or entity with sufficient mail volume to receive its own ZIP Code.
DPV_NO_STAT Indicates the deliverability of the Address:
Y
Address is valid.
N
Address is not valid.
DPV_SHUTDOWN Value can be Y or N.

This is for internal purposes. Does not impact end user and should be ignored.
DPV_VACANT
Y
Address is vacant.
N
Address is not vacant.
sourceDictionary (String) Identifies the dictionary that is the source for the candidate information and data. The source dictionary is a 0-based integer value that indicates which configured dictionary the candidate came from. If you only have a single dictionary this will always be "0".
matching object. Indicates what parts of the input matched; consisting of the following elements:
matchOnAddressNumber (Boolean) Indicates if the input address number matched the candidate's address number.
True
The input address number matched the candidate's address number.
False
The input address number did not match the candidate's address number.
matchOnPostCode1 (Boolean) Indicates if the input postCode1 field matched the candidate's postCode1 field.
True
The input postCode1 matched the candidate's postCode1.
False
The input postCode1 did not match the candidate's postCode1.
matchOnPostCode2 (Boolean) Indicates if the input postCode2 field (post code extension) matched the candidate's postCode2 field.
True
The input postCode2 matched the candidate's postCode2.
False
The input postCode2 did not match candidate's postCode2.
matchOnAreaName1 (Boolean) Indicates if the input areaName1 field matched the candidate's areaName1 field.
True
The input areaName1 matched the candidate's areaName1.
False
The input areaName1 did not match the candidate's areaName1.
matchOnAreaName2 (Boolean) Indicates if the input areaName2 field matched the candidate's areaName2 field.
True
The input areaName2 matched the candidate's areaName2.
False
The input areaName2 did not match the candidate's areaName2.
matchOnAreaName3 (Boolean) Indicates if the input areaName3 field matched the candidate's areaName3 field.
True
The input areaName3 matched the candidate's areaName3.
False
The input areaName3 did not match the candidate's areaName3.
matchOnAreaName4 (Boolean) Indicates if the input areaName4 field matched the candidate's areaName4 field.
True
The input areaName4 matched the candidate's areaName4.
False
The input areaName4 did not match the candidate's areaName4.
matchOnStreetName (Boolean) Indicates if the input street name matched the candidate's street name.
True
The input street name matched the candidate's street name.
False
The input street name did not match the candidate's street name.
matchOnStreetType (Boolean) Indicates if the input street type matched the candidate's street type.
True
The input street type matched the candidate's street type.
False
The input street type did not match the candidate's street type.
matchOnStreetDirectional (Boolean) Indicates if the input street directional matched the candidate's street directional.
True
The input street directional matched the candidate's street directional.
False
The input street directional did not match the candidate's street directional.
matchOnPlaceName (Boolean) Indicates if the input place name matched the candidate's place name.
True
The input place name matched the candidate's place name.
False
The input place name did not match the candidate's place name.
geometry object. Returned geocode consisting of the following elements:
coordinates (Double) The candidate's geocode, specified as x (longitude) and y (latitiude) coordinates separated by a comma.
crs (String) The coordinate reference system used for the candidate's geocode.
type (String) Geometry type. The return value is always Point.
address object. Returned candidate address which may contain some of the following elements:
Note: The meaning, valid values and support of the following address elements vary by country:
  • placeName
  • mainAddress
  • lastLine
  • areaName1
  • areaName2
  • areaName3
  • areaName4
  • postalCode
  • country

In addition, there are certain matching and geocoding options that vary by country. It is important to review the information specific to your country/countries. To locate your country's information, refer to the Country Reference Listing and ISO 3166-1 Country Codes sections in the appendix.
mainAddressLine (String) Candidate address line.
addressLastLine (String) Candidate last address line.
placeName (String) Firm, company, organization, business or building name.
areaName1 (String) State, province or region.
areaName2 (String) County or district.
areaName3 (String) City, town or suburb.
areaName4 (String) Locality
postCode1 (String) Main postal code.
postCode2 (String) Secondary postal code, where one exists.
country (String) Country
addressNumber (String) House or building number.
streetName (String) Street name.
unitType (String) The type of unit, such as Apt., Ste. and Bldg.
unitValue (String) The unit value/number, such as "3B".
customFields (Object) The fields and corresponding values returned are country-specific. Refer to the Country-Specific Information sections in the appendix.
ranges: CandidateRange object. Contains information about a candidate's ranges, consisting of the following elements:
placeName (String) If applicable, indicates the name of the candidate's place or building.
lowHouse (String) Indicates the low house number in the candidate's street range.
highHouse (String) Indicates the high house number in the candidate's street range.
side (String) Provides information on the side of street that the candidate's range is located.
LEFT
The range is on the left side of the street.
RIGHT
The range is on the right side of the street.
BOTH
The range is on both the left and right side of the street.
UNKNOWN
No information is available on the side of the street this range is located.
oddEvenIndicator (String) Provides information on the house numbering of the candidate's range.
ODD
The range contains odd house numbers.
EVEN
The range contains even house numbers.
BOTH
The range contains both odd and even house numbers.
IRREGULAR
The range contains both even and odd numbers in an irregular order.
UNKNOWN
No information is available on the odd/even house numbering on this range.
customValues (Map) A map of local values associated with the candidate's range.
units: CandidateRangeUnit object. Contains information about a candidate range's units, consisting of the following elements:
placeName (String) If applicable, indicates the name of the candidate's place or building.
unitType (String) Indicates the unit type (APT, STE, etc.).
highUnitValue (String) Indicates the high unit number for this range unit.
lowUnitValue (String) Indicates the low unit number for this range unit.
customValues (Map) A map of local values associated with the unit.