Service output

A response from the ArcGIS Geocoding service includes match accuracy and output fields information.

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 will 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 ArcGIS Geocoding service.

For example, a search for Avenida República de El Salvador 70, Distrito Federal, MEX returns a PointAddress match as the top candidate. This is the most precise match level because it represents a building rooftop. If you search for a house number that doesn't exist on the same street, such as Avenida República de El Salvador 700, Distrito Federal, MEX, a StreetName candidate is returned. This match indicates a lower level of precision because the output location is at the center of the street segment named Avenida República de El Salvador. You can use the category parameter to filter out unwanted values from the response. For instance, if you're delivering a package, you need PointAddress or StreetAddress matches, because delivering something to a street center or city centroid won't work.

Geocoding accuracy varies by region and country. The SubAddress match level is the most accurate, followed by PointAddress and StreetAddress . The StreetName match level can be 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 does 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 ArcGIS Geocoding service, as well as the request types for which the fields are returned.

Field	Description	Supported request types
`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.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`address`	The complete matching address returned for `findAddressCandidates` and `geocodeAddresses` geocode requests. Example: 380 New York St, Redlands, California, 92373	`findAddressCandidates` `geocodeAddresses`
`address` (`reverseGeocode` only)	The full street address of a location, including house number and street name. Example: 380 New York St Note This is different than the `address` field that is returned in responses for `findAddressCandidates` and `geocodeAddresses` requests. It is only returned for `reverseGeocode` . It is analogous to the `StAddr` output field for `findAddressCandidates` and `geocodeAddresses` .	`reverseGeocode`
`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. Refer to the description of the locationType parameter for more information about how the location output field relates to the x and y output attributes. For `reverseGeocode` specifically, refer to the description of the `returnInputLocation` parameter to learn how it can be used to modify the output location coordinates.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`ResultID`	This is only returned for `geocodeAddresses` requests. 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.	`geocodeAddresses`
`Loc_name`	The name of the locator used to return a particular match result. Note The `Loc_name` field is used internally by ArcGIS software and is not intended for use by client applications.	`findAddressCandidates` `geocodeAddresses`
`Status`	Indicates whether a geocode request results in a match, a tie, or is unmatched. The possible values are the following: `M` —Matched. The returned address matches the request and is the highest scoring candidate. `T` —Tied. The returned address matches the request but has the same score as one or more additional candidates. `U` —Unmatched. No addresses match the request.	`findAddressCandidates` `geocodeAddresses`
`Score`	A number from 1–100 indicating the degree to which the input tokens in a geocoding request match the address components in a candidate record. A score of 100 represents a perfect match, while lower scores represent decreasing match accuracy.	`findAddressCandidates` `geocodeAddresses`
`Match_addr`	The complete address returned for the geocode request. The format is based on address standards for the country in which the address is located.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`LongLabel`	A longer version of the `Match_addr` value containing more administrative information.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`ShortLabel`	A shortened version of the `Match_addr` value.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Addr_type`	The match level for a geocode request. Supported match levels vary in different countries. The possible values are the following: `Subaddress` —A subset of a `PointAddress` value that represents a house or building subaddress location, such as an apartment unit, floor, or individual building within a complex. The `UnitName` , `UnitType` , `LevelName` , `LevelType` , `BldgName` , and `BldgType` field values help to distinguish subaddresses that may be associated with the same `PointAddress` value. Reference data consists of point features with an associated house number, street name, and subaddress elements, along with administrative divisions and optional postal code. Example: 3836 Emerald Ave, Suite C, La Verne, CA, 91750. `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` / `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. Example: 380 New York St, Redlands, CA, 92373. `StreetAddress` —A street address that differs from the `PointAddress` value because the house number is interpolated from a range of numbers. Reference data contains street center lines with house number ranges, along with administrative divisions and optional postal code information. 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. Example: Redlands Blvd & New York St, Redlands, CA, 92373. `StreetAddressExt` —An interpolated street address match that is returned when `=true` and the input house number exceeds the house number range for the matched street segment. `DistanceMarker` —A street address that represents the linear distance along a street, typically in kilometers or miles, from a designated origin location. Example: Carr 682 KM 4, Barceloneta, 00617. `StreetMidBlock` —The estimated midpoint of a range of house numbers along a street segment that correspond to a city block. The location returned for a `StreetMidBlock` match is more precise than that of a `StreetName` match, but less precise than a `StreetAddress` match. This value is currently only functional for the United States. Example: 100 Block of Grant Ave, Millville, New Jersey. `StreetBetween` —The center point of a street that is located between two specified cross streets. The location returned for a `StreetBetween` match is more precise than that of a `StreetName` match, but less precise than a `StreetAddress` match. This Addr_type is currently only functional for the United States. Example: Davison Rd between Pine Hill Rd and Ridgetop Ln, Henniker, New Hampshire. `StreetName` —This is 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. Example: W Olive Ave, Redlands, CA, 92373. `Locality` —A place-name representing a populated place. The Type output field provides more detailed information about the type of populated place. Possible `Type` values for `Locality` matches include `Block` , `Sector` , `Neighborhood` , `District` , `City` , `MetroArea` , `County` , `State or Province` , `Territory` , `Country` , and `Zone` . Example: Bogotá, COL `PostalLoc` —A combination of postal code and city name. Reference data is typically a combination of postal boundaries and administrative (locality) boundaries. 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. Example: 90210-3841. `Postal` —A postal code. Reference data is postal code points. Example: 90210 USA. `POI` —Points of interest. Reference data consists of businesses, landmarks, and geographic features. Example: Starbucks. `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. `XY` —The match based on the assumption that the first coordinate of the input is longitude and the second is latitude. `YX` —This is returned as `Addr_type` for the candidate, which assumes that latitude is the first number in the input, followed by longitude . `MGRS` —A Military Grid Reference System (MGRS) location, such as 46VFM5319397841. `USNG` —A United States National Grid (USNG) location, such as 15TXN29753883. This `Addr_type` value is only returned when the category parameter is set to `USNG` in a findAddressCandidates or geocodeAddresses request.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Type`	The feature type for results returned by a search. The `Type` field only includes a value for candidates with `Addr_type` = `POI` or `Locality` . As an example, for Starbucks, `Type=Coffee Shop` .	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`PlaceName`	The formal name of a geocode match candidate. Example: Paris or Starbucks.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Place_addr`	The full street address of a place, including street, city, and region. Example: 275 Columbus Ave, New York, New York.	`findAddressCandidates` `geocodeAddresses`
`Phone`	The primary phone number of a place of interest (POI). Example: Knott's Berry Farm, `Phone=(714)220-5200` . For other searches, such as address, intersection, and postal code, the field is empty.	`findAddressCandidates` `geocodeAddresses`
`URL`	The URL of the primary website for a place of interest (POI). Example: the University of Georgia, `URL =http://www.uga.edu/` . For other searches, such as address, intersection, and postal code, the field is empty.	`findAddressCandidates` `geocodeAddresses`
`Rank`	A floating-point number value indicating the priority 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. The `Rank` field is used to sort results for ambiguous queries such as Lincoln, when no additional information (state) is available. `Rank` values are based on population or feature type.	`findAddressCandidates` `geocodeAddresses`
`AddBldg`	The name of a building. Example: Empire State Building.	`findAddressCandidates` `geocodeAddresses`
`AddNum`	The alphanumeric value that represents the portion of an address typically known as a house number or building number. Example: in the address 380 New York Street, `AddNum = 380` . This value is returned for `PointAddress` and `StreetAddress` matches only.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`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.	`findAddressCandidates` `geocodeAddresses`
`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.	`findAddressCandidates` `geocodeAddresses`
`AddRange`	The full house number range for the street segment that an address lies on, in the format AddNumFrom-AddNumTo. For example, the `AddRange` value for street address 123 Main St may be 101-199.	`findAddressCandidates` `geocodeAddresses`
`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). Note `Side` is a legacy field that is kept in place only to support applications that expect it to be present in the REST response. The field is empty for most addresses returned by the geocoding service. It should not be used for analysis purposes.	`findAddressCandidates` `geocodeAddresses`
`StPreDir`	An address element defining the direction of a street and occurs before the primary street name. Example: North in North Main Street.	`findAddressCandidates` `geocodeAddresses`
`StPreType`	An address element defining the leading type of a street. Example: the Spanish term Avenida in Avenida Central or the French term Rue in Rue Lapin.	`findAddressCandidates` `geocodeAddresses`
`StName`	An address element defining the primary name of a street. Example: Main in North Main Street.	`findAddressCandidates` `geocodeAddresses`
`StType`	An address element defining the trailing type of a street. Example: Street in Main Street.	`findAddressCandidates` `geocodeAddresses`
`StDir`	An address element defining the direction of a street, which occurs after the primary street name. Example: North in Main Street North.	`findAddressCandidates` `geocodeAddresses`
`BldgName`	The name or number of a building subunit. Example: A in building A.	`findAddressCandidates` `geocodeAddresses`
`BldgType`	The classification of a building subunit. Examples are building, hangar, and tower.	`findAddressCandidates` `geocodeAddresses`
`LevelType`	The classification of a floor subunit. Examples are floor, level, department, and wing.	`findAddressCandidates` `geocodeAddresses`
`LevelName`	The name or number of a floor subunit. Example: 3 in level 3.	`findAddressCandidates` `geocodeAddresses`
`UnitType`	The classification of a unit subunit. Examples are unit, apartment, flat, office, and suite.	`findAddressCandidates` `geocodeAddresses`
`UnitName`	The name or number of a unit subunit. Example: 2B in apartment 2B.	`findAddressCandidates` `geocodeAddresses`
`SubAddr`	The full subunit value for a candidate with `Addr_type=Subaddress` that includes `<subunit type>` + `<subunit name>` . For example, if the subaddress candidate is an apartment unit, `SubAddr` = `UnitType` + `UnitName` . Example: Apt 4B	`findAddressCandidates` `geocodeAddresses`
`StAddr`	The street address of a place, without city and region. Example: 275 Columbus Ave.	`findAddressCandidates` `geocodeAddresses`
`Block`	The name of the block-level administrative division for a candidate. The `Block` value is the smallest administrative area for a country. It can be described as a subdivision of sector or neighborhood or a named city block. It is not commonly used.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Sector`	The name of the sector-level administrative division for a candidate. The `Sector` value is a subdivision of a neighborhood or district, or represents a collection of blocks. It is not commonly used.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Nbrhd`	The name of the neighborhood-level administrative division for a candidate. The `Nbhrhd` value is a subsection of a city or district.	`findAddressCandidates` `geocodeAddresses`
`Neighborhood`	The name of the neighborhood-level administrative division for a candidate. The `Neighborhood` value is a subsection of a city or district. Note This is analogous to the `Nbhrhd` output field for `findAddressCandidates` and `geocodeAddresses` requests.	`reverseGeocode`
`District`	The name of the district-level administrative division for a candidate. Such as a subdivision of a city.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`City`	The name of the city-level administrative division for a candidate. The `City` value is a subdivision of a subregion or region.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`MetroArea`	The name of the metropolitan area-level administrative division for a candidate. It is an urban area consisting of a large city and the smaller cities surrounding it. The value can potentially intersect multiple subregions or regions. An example is Kolkata Metropolitan Area in India.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Subregion`	The name of the subregion-level administrative division for a candidate. The `Subregion` value is a subdivision of a region.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Region`	The name of the region-level administrative division for a candidate. It is a subdivision of a country or territory. It is typically the largest administrative area for a country if the `Territory` administrative division is not used.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`RegionAbbr`	The abbreviated region name. The `RegionAbbr` value for California is CA.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Territory`	The name of the territory-level administrative division for a candidate. It is a subdivision of country. It is not commonly used. The Sudeste macroregion of Brazil, which encompasses the states of Espírito Santo, Minas Gerais, Rio de Janeiro and São Paulo, is an example.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Postal`	An alphanumeric address element defining the primary postal code. Example: V7M 2B4 for a Canadian postal code and 92374 for a United States postal code.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`PostalExt`	An alphanumeric address element defining the postal code extension. Example: 8100 in USA postal code 92373-8110.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Country`	A 3-character code for a country. Example: Canada is CAN. A list of supported countries and codes is available in Geocode data coverage. This field is returned by the `findAddressCandidates` and `geocodeAddresses` operations.	`findAddressCandidates` `geocodeAddresses`
`CountryCode`	A 3-character code for a country. Example: Canada is CAN. A list of supported countries and codes is available in Geocode data coverage. Note This is analogous to the `Country` output field for `findAddressCandidates` and `geocodeAddresses` requests.	`reverseGeocode`
`CntryName`	The full country name for an address candidate. Example: 日本 (Japan). The name may be in the same language as the input address or in the language specified by the `langCode` parameter for the request. If the full country name is not available in the specified language, the primary language of the country that the address candidate is in is used. Information about supported languages by country is available in Geocode data coverage. This field is returned by the `findAddressCandidates` , `geocodeAddresses` , and `reverseGeocode` operations.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`LangCode`	A 3-character language code representing the language of the address. Example: ENG is English.	`findAddressCandidates` `geocodeAddresses`
`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.	`findAddressCandidates`
`X`	The primary x-coordinate of an address returned by the ArcGIS Geocoding service in spatial reference WGS84 (WKID 4326).	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`Y`	The primary y-coordinate of an address returned by the ArcGIS Geocoding service in spatial reference WGS84 (WKID 4326).	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`InputX`	The x-coordinate that was submitted in a `reverseGeocode` request for the `location` parameter	`reverseGeocode`
`InputY`	The y-coordinate that was submitted in a `reverseGeocode` request for the `location` parameter	`reverseGeocode`
`DisplayX`	The display x-coordinate of an address returned by the ArcGIS Geocoding service in spatial reference WGS84 (WKID 4326). For most types of matches, the `X` and `DisplayX` values are the same. For matches of `Addr_type` , `PointAddress` , and `Subaddress` specifically, the values may be different. In general, for `PointAddress` and `Subaddress` matches, `DisplayX` represents the x-coordinate value of the building rooftop or parcel centroid for the address, and the `X` value represents the x-coordinate of the street-side location for the address. There are exceptions however. Some address data sources used by the ArcGIS Geocoding service only provide the rooftop location of `PointAddress` and `Subaddress` features. However, for some `PointAddress` and `Subaddress` features, only the street-side location is available. For these cases, the `X` and `DisplayX` values are equivalent.	`findAddressCandidates` `geocodeAddresses`
`DisplayY`	The display y-coordinate of an address returned by the ArcGIS Geocoding service in spatial reference WGS84 (WKID 4326). For most types of matches, the `Y` and `DisplayY` values are the same. For matches of `Addr_type` , `PointAddress` , and `Subaddress` specifically, the values may be different. In general, for `PointAddress` and `Subaddress` matches, `DisplayY` represents the y-coordinate value of the building rooftop or parcel centroid for the address, and the `Y` value represents the y-coordinate of the street-side location for the address. There are exceptions however. Some address data sources used by the ArcGIS Geocoding service only provide the rooftop location of `PointAddress` and `Subaddress` features. However, for some `PointAddress` and `Subaddress` features, only the street-side location is available. For these cases, the `Y` and `DisplayY` values are equivalent.	`findAddressCandidates` `geocodeAddresses`
`Xmin`	The minimum x-coordinate for the display extent of a feature returned by the ArcGIS 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.	`findAddressCandidates` `geocodeAddresses`
`Xmax`	The maximum x-coordinate for the display extent of a feature returned by the ArcGIS 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.	`findAddressCandidates` `geocodeAddresses`
`Ymin`	The minimum y-coordinate for the display extent of a feature returned by the ArcGIS 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.	`findAddressCandidates` `geocodeAddresses`
`Ymax`	The maximum y-coordinate for the display extent of a feature returned by the ArcGIS 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.	`findAddressCandidates` `geocodeAddresses`
`ExInfo`	A collection of strings from the input that could not be matched to any part of an address and were used to score or penalize the result.	`findAddressCandidates` `geocodeAddresses`
`extent`	The minimum bounding rectangle of the output match feature as specified by the `Xmin` , `Ymin` , `Xmax` , and `Ymax` field values. 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.	`findAddressCandidates`
`StrucType`	A designation for a structure or building that describes its primary usage. These are the possible values: `Residential` —A dwelling where people live. `Commercial` —A business facility, such as an office building, store, or warehouse. Only geocoding candidates that have `Addr_type` values of `PointAddress` or `Subaddress` will include a value for the `StrucType` field. Note Currently the `StrucType` field is only supported for PointAddress and Subaddress records in USA. Not all such records will include a value for this field.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`
`StrucDet`	Related to `StrucType`. A more detailed usage description for a structure or building. For addresses with `StrucType` value `Residential`, the following `StrucDet` values are supported: `Single Family` —A detached single-family dwelling. `Multifamily` —A building that includes multiple separate housing units, such as an apartment building. For addresses with `StrucType` value `Commercial`, the following `StrucDet` values are supported: `Agricultural` `Industrial` `Lodging` `Medical` `Office` `Recreation` `Retail` `Transport` `Utilities` `Warehouse` Only geocoding candidates that have `Addr_type` values of `PointAddress` or `Subaddress` will include a value for the `StrucDet` field. Note Currently the `StrucDet` field is only supported for PointAddress and Subaddress records in USA. Not all such records will include a value for this field.	`findAddressCandidates` `geocodeAddresses` `reverseGeocode`

Service responses

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

Error codes

Error codes are returned when the service cannot complete a request. This can be due to invalid parameters 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	Details	Cause	ExtendedCode
Unable to complete operation.	"<parameter name> parameter value exceeds the maximum length of <maximum length> characters allowed for the parameter value."	This error is returned if a parameter value contains too many characters. For example, if the singleLine parameter value exceeds 200 characters, this error is returned.	-2147467259
Unable to complete operation.	"Invalid reverse geocode values provided in input"	This error is returned when the location parameter in a reverseGeocode request includes a value that isn't a valid set of coordinates.	-2147467259
Unable to complete operation.	"magicKey entered is invalid"	This error is returned when the magicKey parameter in a findAddressCandidates request includes an invalid value.	-2147467259
Unable to complete operation.	"MagicKey was not generated from the current release and is no longer valid"	This error is returned when the magicKey parameter in a findAddressCandidates request includes a value that corresponds to a different version of the software than the one which is handling the request.	-2147467259
Unable to complete operation.	none	This error is returned when the addresses parameter in a geocodeAddresses request is missing, invalid, or poorly formed. For example, if the addresses JSON object is missing a required comma or if the parameter name is misspelled, this error is returned.	-2147467259
Unable to complete operation.	none	This error is returned when a reverseGeocode request does not include the required location parameter.	-2147467259
"Cannot perform query. Invalid query parameters."	"Unable to find address for the specified location."	This error is returned when no match can be found for a reverseGeocode operation.	none
"Invalid or missing input parameters."	none	This error is returned if a request is missing a required parameter, such as when a suggest request does not include the required text parameter.	-2147024809

Error code 403

Message	Details	Cause	ExtendedCode
"Token is valid but access is denied."	"User does not have permissions to store geocoding results."	This error is returned when a user with insufficient privileges attempts to store the results of a findAddressCandidates operation (that is, `forStorage=true` in the request).	-2147200253
"Token is valid but access is denied."	"User does not have permissions to store reverse geocoding results."	This error is returned when a user with insufficient privileges attempts to store the results of a reverseGeocode operation (that is, `forStorage=true` in the request).	-2147200253
"Token is valid but access is denied."	"User does not have permissions to access geocodeAddresses."	This error is returned when a user with insufficient privileges attempts to batch geocode a table of addresses.	-2147200253

Error code 499

Message	Details	Cause	ExtendedCode
"Token required but not passed in the request."	"Token required"	This error is returned when a token is required but was not included in a request, such as a geocodeAddresses request or when `forStorage=true` in a findAddressCandidates or reverseGeocode request.	none

Error code 500

Message	Details	Cause	ExtendedCode
"Error finding address candidates"	none	This error is returned when the casing of the service name in a findAddressCandidates request is incorrect, such as "world" instead of "World".	none
"Error performing reverse geocode operation"	none	This error is returned when the casing of the service name in a reverseGeocode request is incorrect, such as "world" instead of "World".	none
"Error performing suggest operation"	none	This error is returned when the casing of the service name in a suggest request is incorrect, such as "world" instead of "World".	none
"Error performing geocode addresses operation"	none	This error is returned when the casing of the service name in a geocodeAddresses request is incorrect, such as "world" instead of "World".	none

Error code 504

Message	Details	Cause	ExtendedCode
"Gateway timeout"	none	This error is returned when a request takes longer than 60 seconds to complete. It may indicate that the service is temporarily unavailable. A possible solution is to try the request again at a later time. When it's 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.	none

Remote service responses

There are responses returned when certain conditions related to remote services are encountered (specific to China and South Korea).

Request to remote service times out

When a findAddressCandidates request to the remote service exceeds the request timeout threshold, the following JSON response is returned:

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [

 ],
 "responseInfo": {
  "message": "Time out code 2"
 }
}

Request to remote service is incorrectly formatted

When a findAddressCandidates request to the remote service includes a formatting problem, such as invalid JSON or incorrect parameters, the following response is returned:

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [

 ],
 "responseInfo": {
  "message": "Remote Response Error 3"
 }
}

This is the response returned for a reverseGeocode request under the same conditions:

Use dark colors for code blocksCopy
{
 "error": {
  "code": 400,
  "message": "Cannot perform query. Invalid query parameters.",
  "details": [
   "Unable to find address for the specified location."
  ],
 },
	"responseInfo": {
		"message": "Remote Response Error 3"
	}
}

Multiple consecutive errors returned by remote service

If there are several consecutive time out or error responses returned by the remote service, it is assumed that the remote service is unavailable, unstable, or is blocked temporarily. During the time the service is blocked, requests to the remote service result in empty responses with the following responseInfo message (for findAddressCandidates requests):

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [

 ],
 "responseInfo": {
  "message": "Service code 4"
 }
}

No matches returned

When the service cannot find any matches for a request, the JSON responses below are returned.

findAddressCandidates

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [

 ]
}

suggest

Use dark colors for code blocksCopy
{
 "suggestions": [

 ]
}

reverseGeocode

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

geocodeAddresses

Use dark colors for code blocksCopy
{
   "address": "",
   "score": 0,
   "attributes": {
    "ResultID": 2,
    "Loc_name": "World",
    "Status": "U",
    "Score": 0,
    "Match_addr": "",
    "LongLabel": "",
    "ShortLabel": "",
    "Addr_type": "",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": 0,
    "AddBldg": "",
    "AddNum": "",
    "AddNumFrom": "",
    "AddNumTo": "",
    "AddRange": "",
    "Side": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "BldgType": "",
    "BldgName": "",
    "LevelType": "",
    "LevelName": "",
    "UnitType": "",
    "UnitName": "",
    "SubAddr": "",
    "StAddr": "",
    "Block": "",
    "Sector": "",
    "Nbrhd": "",
    "District": "",
    "City": "",
    "MetroArea": "",
    "Subregion": "",
    "Region": "",
    "RegionAbbr": "",
    "Territory": "",
    "Zone": "",
    "Postal": "",
    "PostalExt": "",
    "Country": "",
    "CntryName": "",
    "LangCode": "",
    "Distance": 0,
    "X": 0.0,
    "Y": 0.0,
    "DisplayX": 0.0,
    "DisplayY": 0.0,
    "Xmin": 0.0,
    "Xmax": 0.0,
    "Ymin": 0.0,
    "Ymax": 0.0,
    "ExInfo": "",
    "StrucType": "",
    "StrucDet": ""
   }
  }
 ]
}

Response for unsupported `category` value

If an invalid category value is passed in a request, a responseInfo message is returned by the service which contains information about the invalid category value. If a list of category values is passed in the request, and one or more of the values are invalid, the response will include any candidates which match the request parameters in addition to the responseInfo object describing the invalid category values. This is a change to the way invalid category values are handled. Previously, the response consisted of a generic error message without any matching candidates or information about invalid categories.

Response for invalid category value in `findAddressCandidates` request

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [

 ],
 "responseInfo": {
  "message": "Invalid category value '<category>' in request"
 }
}

Response for invalid category value in `suggest` request

Use dark colors for code blocksCopy
{
 "suggestions": [

 ],
 "responseInfo": {
  "message": "Invalid category value '<category>' in request"
 }
}

Output fields for StreetInt candidates

Intersection candidates, when 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 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

Use dark colors for code blocksCopy
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=New York St and Redlands Blvd, Redlands, CA&outFields=*&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=New%20York%20St%20and%20Redlands%20Blvd%2C%20Redlands%2C%20CA&outFields=*&f=pjson&token=<ACCESS_TOKEN>

JSON response

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "New York St & W Redlands Blvd, Redlands, California, 92373",
   "location": {
    "x": -117.195698701402,
    "y": 34.059613898424
   },
   "score": 99.84,
   "attributes": {
    "Loc_name": "World",
    "Status": "T",
    "Score": 99.84,
    "Match_addr": "New York St & W Redlands Blvd, Redlands, California, 92373",
    "LongLabel": "New York St & W Redlands Blvd, Redlands, CA, 92373, USA",
    "ShortLabel": "New York St & W Redlands Blvd",
    "Addr_type": "StreetInt",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "New York St & W Redlands Blvd, Redlands, California, 92373",
    "Phone": "",
    "URL": "",
    "Rank": 20,
    "AddBldg": "",
    "AddNum": "",
    "AddNumFrom": "",
    "AddNumTo": "",
    "AddRange": "",
    "Side": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "StPreDir1": "",
    "StPreType1": "",
    "StName1": "New York",
    "StType1": "St",
    "StDir1": "",
    "StPreDir2": "W",
    "StPreType2": "",
    "StName2": "Redlands",
    "StType2": "Blvd",
    "StDir2": "",
    "BldgType": "",
    "BldgName": "",
    "LevelType": "",
    "LevelName": "",
    "UnitType": "",
    "UnitName": "",
    "SubAddr": "",
    "StAddr": "New York St & W Redlands Blvd",
    "Block": "",
    "Sector": "",
    "Nbrhd": "",
    "District": "",
    "City": "Redlands",
    "MetroArea": "",
    "Subregion": "San Bernardino County",
    "Region": "California",
    "RegionAbbr": "CA",
    "Territory": "",
    "Zone": "",
    "Postal": "92373",
    "PostalExt": "",
    "Country": "USA",
    "CntryName": "United States",
    "LangCode": "ENG",
    "Distance": 0,
    "X": -117.195698701402,
    "Y": 34.059613898424,
    "DisplayX": -117.195698701402,
    "DisplayY": 34.059613898424,
    "Xmin": -117.196698701402,
    "Xmax": -117.194698701402,
    "Ymin": 34.058613898424,
    "Ymax": 34.060613898424,
    "ExInfo": "",
    "StrucType": "",
    "StrucDet": "",
    "StrucType1": "",
    "StrucType2": "",
    "StrucDet1": "",
    "StrucDet2": ""
   },
   "extent": {
    "xmin": -117.196698701402,
    "ymin": 34.058613898424,
    "xmax": -117.194698701402,
    "ymax": 34.060613898424
   }
  }