GeocodeServiceResponse Object

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.
Name Type 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.
Note: This field is not returned for USA. For geocode precision information for USA, see Location Codes.
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.

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 City name.

Z Post code.

A Geocoding dataset.

U Custom user dataset.
Note: For more detailed information including country-specific meanings and values, see Global Result Codes.
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.
matchOnCountry Boolean Indicates if the candidate country matches the input country.

True The candidate country matches the input country.

False The candidate country does not match the input country.
matchOnAllStreetFields Boolean Indicates if the all of the input street fields matched all of the candidate's street fields.

True All of the input street fields matched all of the candidate's street fields.

False One or more of the input street fields do not match the candidate's street fields.
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:
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.
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.
totalPossibleCandidates Integer Indicates how many match candidates were found.