Service output

Match accuracy

The accuracy of a match returned by a search depends on the amount and quality of information submitted. The location of the match can vary from a highly precise point address to a more general postal code centroid. Providing high quality and complete information in a geocoding request can significantly improve the match quality.

For example, if you search for an address such as 100 Main St Springfield, several matches will be returned, because there are many cities in the United States named Springfield that contain a street named Main St. In this case, more accurate results would be obtained by including state or postal code information in the request.

The Addr_type output field can be used as an indicator of the precision of geocode results. It describes the match level of the results returned by the World Geocoding Service. A list with descriptions for each of the match levels is available Service output.

As an example, a search for 380 New York St. Redlands CA returns multiple matches with scores of 100, which include matches at the PointAddress, StreetAddress, StreetName, and AdminPlaces match levels. The PointAddress result will be the most precise; the StreetName and AdminPlaces results represent decreasing levels of precision. You can specify in the request that the Addr_type field be returned, and use application logic to filter out undesired values from the response. For instance, if you were delivering a package, you would need PointAddress or StreetAddress matches, because delivering something to a postal code or city centroid would not work.

Geocoding accuracy will vary by region and country. PointAddress and BuildingName are the most accurate match levels, followed by StreetAddress. StreetName can be very accurate if the street is a short segment, but less so if it is a long segment.

The list of Addr_type values (see the table below) is a combined list of all match levels for all countries; each country will not necessarily support each match level.

Output fields

The following table describes all of the fields that can be returned in a response from the World Geocoding Service.

Field

Description

spatialReference

The spatial reference of the output match location coordinates as specified by the wkid and latestWkid properties. The outSR input parameter determines the spatial reference. This is always returned by default.

address

Complete matching address returned for findAddressCandidates and geocodeAddresses geocode requests. This is always returned by default.

extent

The minimum bounding rectangle of the output match feature as specified by the xmin, ymin, xmax, and ymax properties. The spatial reference of the x and y coordinates is defined by the spatialReference output field. This is always returned by default for findAddressCandidates geocode requests only.

location

The point coordinates of the output match location as specified by the x and y properties. The spatial reference of the x and y coordinates is defined by the spatialReference output field. Always returned by default for findAddressCandidates and findAddressCandidates geocode requests only.

ResultID

Only returned by batch geocoding processes. Each record in a batch geocode response includes a ResultID value, which equals the OBJECTID value of the corresponding input address record. It can be used to join the output fields in the response to the attributes in the original address table.

Loc_name

The name of the component locator used to return a particular match result. It is a combination of the 3-digit ISO country code for the country where the match is located and the address locator style, such as StreetAddress, for example, USA.StreetAddress

NoteNote:

The Loc_name field is used internally by ArcGIS software and is not intended for use by client applications.

Status

Indicates whether a batch geocode request results in a match, tie, or unmatch. This field is only returned by thegeocodeAddresses operation.

Possible values include the following:

  • M—Match. The returned address matches the request and is the highest scoring candidate.
  • T—Tie. The returned address matches the request but has the same score as one or more additional candidates.
  • U—Unmatch. No addresses match the request.

Score

A number from 1–100 indicating the accuracy of the address match. A score of 100 represents a perfect match, while lower scores represent decreasing match accuracy. Score is always returned by default.

Match_addr

Complete address returned for the geocode request. The format is based on address standards for the country where the address is located.

Addr_type

The match level for a geocode request. Supported match levels vary in different countries.

Possible values include the following:

  • PointAddress—A street address based on points that represent house and building locations. Typically, this is the most spatially accurate match level. Reference data contains address points with associated house numbers and street names, along with administrative divisions and optional postal code. The X and Y and geometry output values for a PointAddress match represent the street entry location for the address; this is the location used for routing operations. The DisplayX and DisplayY values represent the rooftop, or actual, location of the address, for example, 380 New York St, Redlands, CA, 92373.
  • BuildingName—A street address based on points representing buildings. This differs from PointAddress because reference data contains building names instead of house number, for example, Nirvana Apartment, 24th Road, Mumbai, 400050.
  • StreetAddress—A street address that differs from PointAddress because the house number is interpolated from a range of numbers. Reference data contains street centerlines with house number ranges, along with administrative divisions and optional postal code information, for example, 647 Haight St, San Francisco, CA, 94117.
  • StreetInt—A street address consisting of a street intersection along with city and optional state and postal code information. This is derived from StreetAddress reference data, for example, Redlands Blvd & New York St, Redlands, CA, 92373.
  • StreetName—Similar to a street address but without the house number. Reference data contains street centerlines with associated street names (no numbered address ranges), along with administrative divisions and optional postal code, for example, W Olive Ave, Redlands, CA, 92373.
  • Admin—A place-name representing the highest-order administrative division. Depending on the country, it can represent a state or province, for example, California.
  • DepAdmin—A place-name representing a higher-order administrative division. Depending on the country, it can represent a county, district, or region. This is smaller than an Admin area, for example: Αττικη.
  • SubAdmin—A place-name representing a lower-order administrative division. Depending on the country, it can represent a municipality or city. This is typically smaller than a DepAdmin area, for example, Ciudad Autónoma de Buenos Aires, CAPITAL FEDERAL.
  • Locality—A place-name representing a populated place such as a city or neighborhood. This is typically the smallest administrative division within a country, for example, Mustafapaşa, Gebze.
  • PostalLoc—A combination of postal code and city name. Reference data is typically a union of postal boundaries and administrative (locality) boundaries, for example, 7132 Frauenkirchen.
  • PostalExt—A postal code with an additional extension, such as the United States Postal Service ZIP+4. Reference data is postal code points with extensions, for example, 90210-3841.
  • Postal—Postal code. Reference data is postal code points, for example, 90210 USA.
  • POI—Points of interest. Reference data consists of administrative division place-names, businesses, landmarks, and geographic features, for example, Starbucks.
  • Zone—City block. Only used in Japan at this time.
  • LatLong—An x/y coordinate pair. The LatLong addr_type is returned when an x/y coordinate pair, such as 117.155579,32.703761, is the search input.
  • RoadKM—A distance marker. Only used in Puerto Rico at this time.

Type

The feature type for results returned by a search. Returned by the WorldGazetteer locator for findAddressCandidates requests. As an example, for Starbucks, Type = "Coffee Shop".

PlaceName

The formal name of a geocode match candidate. This is only returned by the WorldGazetteer locator for findAddressCandidates requests, for example, "Paris" or "Starbucks".

Place_addr

The full street address of a place, including street, city, and region. This is only returned by the WorldGazetteer locator for POI searches. The field is returned but empty for address, intersection, and postal searches, for example, "275 Columbus Ave, New York, New York".

Phone

The primary phone number of a place. Returned by the WorldGazetteer locator for findAddressCandidates requests. For other searches, such as address, intersection, and postal code, the field is empty, for example, Knott's Berry Farm, Phone = "(714)220-5200".

URL

The URL of the primary website for a place. Returned by the WorldGazetteer locator for findAddressCandidates requests. For other searches, such as address, intersection, and postal code, the field is empty, for example, the University of Georgia, URL = "http://www.uga.edu/ ".

Rank

A numerical text value indicating the importance of a result relative to other results with the same name. For example, there are cities in France and Texas named Paris. Paris, France, has a greater population than Paris, Texas, so it has a higher rank. Rank is used to sort results for ambiguous queries such as "Lincoln", where no additional information (state) is available. Rank values are based on population or feature type. Note that Rank is not used with all features, so some responses will contain a blank Rank value.

AddBldg

The name of a building, for example, Empire State Building.

AddNum

The alphanumeric value that represents the portion of an address typically known as a house number or building number, for example, in the address "380 New York Street", AddNum = 380.

This value is returned for PointAddress and StreetAddress matches only.

AddNumFrom

A value representing the beginning number of a street address range. It is relative to direction of feature digitization and is not always the smallest number in the range. This value is provided for StreetAddress results.

AddNumTo

A value representing the ending number of a street address range. It is relative to direction of feature digitization and is not always the largest number in the range. This value is provided for StreetAddress results.

Side

The side of the street where an address resides relative to the direction of feature digitization. This value is not relative to the direction of travel along the street. Possible values are "R" (Right) and "L" (Left).

StPreDir

Address element defining the direction of a street and occurs before the primary street name, for example, "North" in "North Main Street".

StPreType

An address element defining the leading type of a street, for example, the Spanish term "Avenida" in Avenida Central or the French term "Rue" in Rue Lapin.

StName

An address element defining the primary name of a street, for example, "Main" in North Main Street.

StType

An address element defining the trailing type of a street, for example, "Street" in Main Street.

StDir

An address element defining the direction of a street, which occurs after the primary street name, for example, "North" in "Main Street North".

StAddr

The street address of a place, without city and region. This is only returned by the WorldGazetteer locator for POI searches. The field is returned but empty for address, intersection, and postal searches, for example, "275 Columbus Ave".

Nbrhd

The smallest administrative area for a country, typically a neighborhood or other subsection of a city.

City

The next smallest administrative area for a country, typically a city or municipality.

Subregion

The next largest administrative area for a country, typically a county or region.

Region

The largest administrative area for a country, typically a state or province.

Postal

An alphanumeric address element defining the primary postal code, for example, "V7M 2B4" for a Canadian postal code and "92374" for a USA postal code.

PostalExt

An alphanumeric address element defining the postal code extension, for example, "8100" in USA postal code 92373-8110.

Country

A 3-digit ISO 3166-1 code for a country, for example, Canada = "CAN". A list of supported countries and codes is available in Geocode coverage.

LangCode

A 3-digit MARC language code, representing the language of the address, for Example, "ENG" = English. See a list of codes.

Distance

The physical distance in meters from a candidate to a specified location. The Distance output value is calculated for each candidate when the Location input parameter is passed in a request using the findAddressCandidates operation. If the Location parameter is not passed in a request, the value of Distance is zero.

X

The primary x coordinate of an address returned by the World Geocoding Service in spatial reference WGS84 (WKID 4326).

Y

The primary y coordinate of an address returned by the World Geocoding Service in spatial reference WGS84 (WKID 4326).

DisplayX

The display x coordinate of an address returned by the World Geocoding Service in spatial reference WGS84 (WKID 4326). For PointAddress locators, this value represents the actual location of the address (that is, the building or parcel centroid). It differs from the x value, which is derived from a location along the street or the street entry for an address. For all other locators, this value is equal to the x value.

DisplayY

The display y coordinate of an address returned by the World Geocoding Service in spatial reference WGS84 (WKID 4326). For PointAddress locators, this value represents the actual location of the address (that is, the building or parcel centroid). It differs from the y value, which is derived from a location along the street or the street entry for an address. For all other locators, this value is equal to the y value.

Xmin

The minimum x coordinate for the display extent of a feature returned by the World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference.

Xmax

The maximum x coordinate for the display extent of a feature returned by the World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference.

Ymin

The minimum y coordinate for the display extent of a feature returned by the World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference.

Ymax

The maximum y coordinate for the display extent of a feature returned by the World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference.

Responses from the service

As a developer, it's useful to be aware of the various JSON responses that can be returned by the World Geocoding Service for erroneous or invalid requests, or when there are no matches for a request.

Error codes

Error codes are returned when the service cannot complete a request. This can be due to invalid parameters being included in the request or insufficient user permissions. Some potential errors that may be encountered with the service are described below.

Error code 400

Message: "Unable to complete operation."

Possible causes

  • Details: "<parameter name> parameter value exceeds the maximum length of <maximum length> characters allowed for the parameter value." This error is returned if the input parameter value contains too many characters. For example, if the singleLine parameter value exceeds 100 characters, this error is returned.
  • Details: None. Error code 400 may be returned with no detailed message when an invalid category parameter value is included in a request.

Message: "Cannot perform query. Invalid query parameters."

Possible causes

  • Details: "Unable to find address for the specified location." Returned when no match can be found for a reverseGeocode operation.

Message: "Invalid or missing input parameters."

Possible causes

  • Details: None. This error is returned if a request is missing a required parameter.

Error code 403

Message: "Token is valid but access is denied."

Possible causes

  • Details: "User does not have permissions to store geocoding results." Returned when a user with insufficient privileges attempts to store the results of a findAddressCandidates operation (that is, forStorage=true in the request).
  • Details: "User does not have permissions to store reverse geocoding results." Returned when a user with insufficient privileges attempts to store the results of a reverseGeocode operation (that is, forStorage=true in the request).
  • Details: "User does not have permissions to access geocodeAddresses." Returned when a user with insufficient privileges attempts to batch geocode a table of addresses.

Error code 499

Message: "Token required but not passed in the request."

Possible causes

Error code 500

Message: "Error performing <operation name> operation"

Possible causes

  • Details: None. Returned when the casing of the operation name in a request is incorrect, such as reversegeocode instead of reverseGeocode.

Error code 504

Message: "Gateway timeout"

Possible causes

  • Details: None. Returned when a request takes longer than 60 seconds to complete. It may indicate that the service is temporarily down. A possible solution is to try the request again at a later time. When returned by a geocodeAddresses request, it may also indicate there are too many addresses in the input batch. In this case, try adjusting the request so it includes fewer addresses.

No matches returned

When the service cannot find any matches for a request, the following JSON responses are returned:

findAddressCandidates

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  
 ]
}

suggest

{
 "suggestions": [
  
 ]
}

reverseGeocode

{
 "error": {
  "code": 400,
  "message": "Cannot perform query. Invalid query parameters.",
  "details": [
   "Unable to find address for the specified location."
  ]
 }
}

geocodeAddresses

{
   "address": "",
   "score": 0,
   "attributes": {
    "ResultID": 2,
    "Loc_name": "",
    "Status": "U",
    "Score": 0,
    "Match_addr": "",
    "Addr_type": "",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "",
    "AddBldg": "",
    "AddNum": "",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "StAddr": "",
    "Nbrhd": "",
    "City": "",
    "Subregion": "",
    "Region": "",
    "Postal": "",
    "PostalExt": "",
    "Country": "",
    "LangCode": "",
    "Distance": 0,
    "X": 0,
    "Y": 0,
    "DisplayX": 0,
    "DisplayY": 0,
    "Xmin": 0,
    "Xmax": 0,
    "Ymin": 0,
    "Ymax": 0
   }
  }
 ]
}

Output fields for StreetInt candidates

Intersection candidates, where Addr_type = StreetInt, are a special case with respect to output fields. Three sets of output fields are returned for a single StreetInt candidate: one set for the intersection itself and two for the street segments composing the intersection. The additional output fields for the individual street segments are indicated by a "1" or "2" suffix at the end of the output field name. For example, there are three StName output fields for a StreetInt candidate:

  • StName—The StName output field for the intersection
  • StName1—The StName output field for the first street segment of the intersection
  • StName2—The StName output field for the second street segment of the intersection

The following example shows all the output fields included in a JSON response for a StreetInt candidate.

Example: Find an intersection (New York St and Redlands Blvd, Redlands, CA)

Single field request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "New York St & W Redlands Blvd, Redlands, California, 92373",
   "location": {
    "x": -117.19570839692426,
    "y": 34.059490820246253
   },
   "score": 96.469999999999999,
   "attributes": {
    "Loc_name": "USA.StreetAddress",
    "Score": 96.469999999999999,
    "Match_addr": "New York St & W Redlands Blvd, Redlands, California, 92373",
    "PlaceName": "",
    "StAddr": "",
    "Place_addr": "",
    "Nbrhd": "",
    "City": "",
    "Subregion": "",
    "Region": "",
    "Country": "USA",
    "LangCode": "",
    "Phone": "",
    "URL": "",
    "DisplayX": -117.19570899999999,
    "DisplayY": 34.059491000000001,
    "Distance": 0,
    "X": -117.19570899999999,
    "Y": 34.059491000000001,
    "Xmin": -117.19570899999999,
    "Xmax": -117.19570899999999,
    "Ymin": 34.059491000000001,
    "Ymax": 34.059491000000001,
    "Addr_type": "StreetInt",
    "Type": "",
    "Rank": "",
    "Side": "",
    "AddNum": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "Postal": "",
    "Side1": "L",
    "AddNum1": "",
    "AddNumFrom1": "",
    "AddNumTo1": "",
    "StPreDir1": "",
    "StPreType1": "",
    "StName1": "New York",
    "StType1": "St",
    "StDir1": "",
    "City1": "Redlands",
    "Region1": "California",
    "Postal1": "92373",
    "LangCode1": "ENG",
    "Side2": "L",
    "AddNum2": "",
    "AddNumFrom2": "973",
    "AddNumTo2": "999",
    "StPreDir2": "W",
    "StPreType2": "",
    "StName2": "Redlands",
    "StType2": "Blvd",
    "StDir2": "",
    "City2": "Redlands",
    "Region2": "California",
    "Postal2": "92373",
    "LangCode2": "ENG",
    "PostalExt": "",
    "Subregion1": "",
    "Country1": "USA",
    "Xmin1": "",
    "Xmax1": "",
    "Ymin1": "",
    "Ymax1": "",
    "Subregion2": "",
    "Country2": "USA",
    "Xmin2": "",
    "Xmax2": "",
    "Ymin2": "",
    "Ymax2": "",
    "Nbrhd1": "",
    "Nbrhd2": "",
    "PostalExt1": "",
    "PostalExt2": "",
    "AddBldg": "",
    "AddNumFrom": "",
    "AddNumTo": ""
   },
   "extent": {
    "xmin": -117.19570899999999,
    "ymin": 34.059491000000001,
    "xmax": -117.19570899999999,
    "ymax": 34.059491000000001
   }
  },

3/3/2017