The /reverse request determines the address at a particular x,y location. You pass the coordinates of a point location and the service returns the address or place that is closest to the location.
The purpose of reverse geocoding is to answer the question: What's near me? Or more specifically: What's near this location? To best answer this question, the reverse operation returns the most relevant feature near an input location based on a prioritized hierarchy of feature types. With a few exceptions, the same feature types that can be returned by find can also be returned by reverse . As long as the location is within a supported country, a single feature is always returned, even if the location is far from any streets or places. If there are no streets near the input location, large areal features such as parks, universities, zoos, or airports may be returned. If the location isn't within the boundary of this type of feature, a postal code or administrative area (such as a city) is returned.
The hierarchy is summarized in the table below, ordered by descending priority. Unless otherwise noted, each feature type is only returned when the distance between the input location and the feature is within the tolerance specified in the Search Tolerance column.
| Feature type | Search tolerance | Comments |
|---|---|---|
10 meters | Intersections are only returned when | |
StreetAddress (near), DistanceMarker, or StreetName | 3 meters | Candidates of type StreetName are only returned if |
POI centroid | 25 meters | A business or landmark that can be represented by a point. |
10 meters | Subaddress candidates, which can be features such as apartments or floors in a building, are not returned if multiple subaddresses exist at the same x,y location and one of the following conditions is met:
| |
50 meters | A PointAddress match is not returned if it is on the opposite side of the street as the input location, even if it is within 50 meters of the location. | |
StreetAddress (distant), DistanceMarker, or StreetName | 100 meters | Candidates of type StreetName are only returned if |
POI area | within boundary | A business or landmark that can be represented by an area, such as a large park or university. Not available in all countries. |
within boundary | If the input location intersects multiple boundaries, the feature with the smallest area is returned. |
The images below should help with visualizing the reverse feature type hierarchy.
The following image shows a section of a typical map on which a user may click or add points for reverse geocoding.
The following image shows what the same map looks like with the available features for reverse geocoding highlighted: blue dots for StreetInt features, pink dots for POI centroids, green dots for PointAddress features, red lines for street segments, and a brown polygon representing a POI area feature.
In the following image, buffers have been created around the different features based on the search tolerance values from the hierarchy table to illustrate the match types that would be returned for various reverse input locations. Refer to the following examples to see the expected matches for the input locations in the image.
For each number callout in the image above, there is a corresponding example with the same number.
Parameters
| Name | Required | Type | Default | Description |
|---|---|---|---|---|
string | The request response format, either | |||
string | An access token with the required privileges. | |||
string | point | The point from which to search for the closest address. | |||
number |
| The spatial reference of the | ||
boolean | Specifies whether the results of a request are stored. | |||
string | Limits the possible match types. | |||
boolean |
| Returns street intersections. This parameter has been replaced by | ||
string |
| Specifies whether output geometry of | ||
string | Returns specified address component values included in output fields. | |||
string | * | The list of fields to be returned within the | |||
boolean |
| Specifies which coordinates should be returned in the X and Y output fields within the location object of the JSON response |
Required parameters
token
An access token with the required privileges.
- ArcGIS Location Platform: premium:user:geocode:temporary or premium:user:geocode:stored
- ArcGIS Online: premium:user:geocode or premium:user:geocode:stored
token=<ACCESS_TOKEN>To use HTTP headers instead of the token parameter, set the following:
GET <SERVICE_REQUEST> HTTP/1.1
Host: <SERVICE_DOMAIN>
X-Esri-Authorization: Bearer <ACCESS_TOKEN>Learn more about access tokens and privileges in the Security and authentication developer guide.
location
The point from which to search for the closest address. The point can be represented as a simple, comma-separated syntax or as a JSON point object.
The spatial reference of the comma-separated syntax is always WGS84 (in decimal degrees), the same coordinate system as the ArcGIS Geocoding service.
Use JSON formatting to specify any other coordinate system for the input location. Specifically, set the spatial reference using its well-known ID (WKID) value. For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.
Example using simple syntax and the default WGS84 spatial reference
location=103.8767227,1.3330736Example using JSON and the default WGS84 spatial reference
location={x: 103.876722, y: 1.3330736}Example using JSON and specifying a spatial reference (WGS84 Web Mercator Auxiliary Sphere)
location=
{
"x": 11563503,
"y": 148410,
"spatialReference": {
"wkid": 3857
}
}Optional parameters
outSR
The spatial reference of the x,y coordinates returned by a geocode request. This is useful for applications using a map with a spatial reference different than that of the geocode service.
The spatial reference can be specified as either a well-known ID (WKID) or as a JSON spatial reference object. If out is not specified, the spatial reference of the output locations is the same as that of the service. The ArcGIS Geocoding service spatial reference is WGS84 (WKID = 4326).
For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.
Example (102100 is the WKID for the Web Mercator projection)
outSR=102100langCode
The lang parameter sets the language in which reverse-geocoded addresses are returned. Addresses in many countries are available in more than one language; in these cases, the lang parameter can be used to specify which language should be used for addresses returned by the reverse operation. This is useful for ensuring that addresses are returned in the expected language. For example, a web application could be designed to get the browser language and pass it as the lang parameter value in a reverse request.
See the table of supported countries for valid language code values in each country. The Supported Language Codes column provides the valid input values for the lang parameter. Full language names cannot be used with the lang parameter. Only one language code value can be included for the lang parameter in a reverse request.
The default language code for each country is the first one listed in the Supported Language Codes column, highlighted with bold text. It is the default language of addresses returned by the reverse operation for a particular country. For countries with multiple supported languages, the default language is the one spoken by the highest percentage of the country's population. For some countries, not all addresses are available in the default language. If the lang parameter isn't included in a request, or if it is included but there are no matching features with the input language code, the resultant match is returned in the country's default language code.
Similarly, when there are multiple supported languages for a country, it doesn't mean that every address in the country is available in each of the languages. It may be the case that addresses are available in multiple languages for only one region of the country, or that each language is exclusive to a different region and there is no overlap at all. The following are some examples:
- Both English and French are listed as supported languages for Canada. However, there is no overlap between the languages for any addresses in most provinces. In the province of Quebec, only French addresses are available, while English is the only language used for addresses in Ontario.
- In Belgium, where three languages are supported (Dutch, French, and German), addresses are available in the city of Brussels in both Dutch and French. However, in the majority of the country, only a single language is used for addresses.
- In Greece, there is complete address coverage in both Greek and transliterated Greek languages (Greek words translated with Latin characters).
Due to variability of language coverage, the following logic is used to handle the different scenarios that may be encountered.
| Scenario | Result | Example |
|---|---|---|
No | Address is returned in the supported language. | Location in Geneva, Switzerland (only French addresses are supported) Address returned in French language. |
No | Address is returned in the country's default language. | Location in Brussels, Belgium (Dutch and French addresses are supported; Dutch is the default language) Address returned in Dutch language. |
An invalid | Address is returned in the supported language. | Location in Geneva, Switzerland (only French addresses are supported), and Address returned in French language. |
An invalid | Address is returned in the transliterated language. | Location in Athens, Greece (Greek and transliterated Greek are supported), and Transliterated address is returned. |
An invalid | Address is returned in the country's default language. | Location in Athens, Greece (Greek and transliterated Greek are supported; Greek is the default language), and Address returned in Greek language. |
Example
langCode=frforStorage
Specifies whether the results of the operation will be persisted. The default value is false , which indicates the results of the operation can't be stored, but they can be temporarily displayed on a map, for instance. If you store the results, in a database, for example, you need to set this parameter to true .
Applications are contractually prohibited from storing the results of geocoding transactions unless they make the request by passing the for parameter with a value of true and the token parameter with a valid token. Instructions for composing a request with a valid token are provided in Security and authentication.
To learn more about free and paid geocoding operations, stored versus not stored geocoding are explained further.
Example
forStorage=truefeatureTypes
The feature parameter limits the possible match types returned by the reverse operation. Valid values are listed in the feature type hierarchy table. Single or multiple values can be included in the request. If a single value is included, the search tolerance for the input feature type is 500 meters. If multiple values are included, the default search distances specified in the feature type hierarchy table are applied.
Use feature instead of the return parameter to return intersection matches. The return parameter is only supported for backward compatibility with legacy apps. Intersection matches are not returned by reverse unless feature (or return ) is included in the request.
The label for StreetAddress matches includes the house number range for the matching street segment, rather than the interpolated house number value. For instance, reverse with input location -117.196324,34.059217 returns a StreetAddress match with Match . This means that the matching segment has a possible range of house numbers from 1001 to 1199.
If there are multiple Subaddress features with the same x,y value intersected by a reverse geocode location, the label for the Subaddress candidate includes the range of unit numbers for all subaddress records in the stack. For instance, a reverse with input location 151.073457,-33.916374 returns a Subaddress match with label 28 Hampden Rd, Unit 1-8 . It means there are multiple subaddresses at the location with unit numbers such as Unit 1, Unit 2, Unit 3... up to Unit 8.
If more than one value is specified for the parameter, the values must be separated by a comma, with no spaces after the comma.
Example (single featureTypes value)
featureTypes=PointAddressExample (multiple featureTypes values)
featureTypes=PointAddress,StreetAddressreturnIntersection
The return parameter has been replaced by the feature parameter for returning street intersection matches with reverse . It is only supported for backward compatibility with legacy apps. The feature parameter should be used instead of return . If you want to return the nearest street intersection to the input location, pass feature in the reverse request.
A Boolean that indicates whether the service should return the nearest street intersection to the input location. If true , the closest intersection to the input location is returned; if false , the closest address or place to the input location is returned. The default value is false .
Example
returnIntersection=truelocationType
Specifies whether the output geometry of PointAddress and Subaddress matches should be the rooftop point or street entrance location. Valid values are rooftop and street . The default value is rooftop .
Geocode results include one geometry object (the location object), which defines the location of the address, as well as two sets of x,y coordinate values within the attributes object: X /Y , and DisplayX /DisplayY . In most cases, for geocode results with = or Subaddress , the X /Y attribute values describe the coordinates of the address along the street, while the Display /Display values describe the rooftop, or building centroid, coordinates. By default, the geometry returned for geocode results represents the rooftop location of the address (if the rooftop location is available in the source data). This is useful for most spatial analysis and map display purposes. However, for routing scenarios, it may be desirable to use the street location because the rooftop location of some addresses may be offset from a street by a large distance. For these cases, the location parameter can be used to specify that the street entrance geometry should be returned.
It is important to note that location is limited by the address data sources used by the ArcGIS Geocoding service. Not all PointAddress and Subaddress features include rooftop and street location coordinates. For some addresses, only a rooftop location is available; for others, only a street location is provided by the data source. For cases such as this, the location parameter may not function as expected. For example, if only rooftop location coordinates are available for an address, the rooftop geometry will be returned for the geocoded address even when location is requested.
Example
locationType=streetpreferredLabelValues
The preferred parameter allows simple configuration of output fields returned in a response from the ArcGIS Geocoding service by specifying which address component values should be included in output fields. It supports a single value as input. If the parameter is blank or excluded from a request, default address label formats will be used.
A particular address may have multiple city names associated with it. In the United States, for instance, all addresses have a ZIP Code (postal code) assigned to them. Each ZIP Code has one or more associated locality names, which are known as postal cities. There is always one primary postal city value for each ZIP Code. ZIP Codes typically have no set boundaries, and the primary postal city name for the ZIP Code that is assigned to an address may be different than the name of the local city that the address is within.
For addresses in the United States, the ArcGIS Geocoding service includes the primary postal city in response output fields by default. For example, postal code 45420 in Ohio has the primary postal city value Dayton. Addresses in the neighboring city of Kettering are assigned this postal code. It means that the default output fields for all reverse geocoded addresses with postal code 45420, even those within the city of Kettering, will include Dayton as the city. To illustrate, if a user reverse geocodes latitude/longitude coordinates -84.1252005,39.703149 , the match address returned in the response is 2109 E Dorothy Ln, Dayton, Ohio, 45420, even though the address is within the Kettering city limits.
Some organizations may prefer to include the local city name in the response instead of the postal city. The preferred can be used for this purpose. For the previous example, if preferred is included in the request, the output match address in the response will be 2109 E Dorothy Ln, Kettering, Ohio, 45420.
See the following table for supported parameter values.
| Parameter value | Description |
|---|---|
postalCity | Include the primary postal city value in geocoding response output fields. This is the primary name assigned to the postal code of the address. |
localCity | Include the primary local city name in geocoding response output fields. This is the name of the city that the address is within, and may be different than the postal city. |
Example: Single label value
preferredLabelValues=localCityoutFields
The list of fields to be returned within the address object of the reverse JSON response. Descriptions for each of the reverse output fields are available in the Output fields section of this document. The reverse output fields are those for which "Supported request types" = "reverseGeocode" in the table.
The reverse response consists of two objects: address and location . The location object includes the fields that are used for displaying reverse geocode results in a mapping application. The address object includes fields which provide details about the address or place returned for the reverse request, such as the full address, city, place name, and others. The out parameter is only relevant for the address object. The location object is not affected by it.
By default, all possible output fields are returned in the response. In other words, passing out (blank) in the request is functionally the same as passing out .
Examples that returns all output fields
outFields=*Example that returns the specified fields only
outFields=Match_addr,Addr_type,CountryCodereturnInputLocation
The return parameter is a Boolean which can be used to specify which coordinates should be returned in the X and Y output fields within the location object of the JSON response. The default value is false .
- If
true, then the coordinates which were included in thereverserequest for theGeocode locationparameter are returned in theXandYoutput fields in thelocationobject of the JSON response. - If false, then the coordinates of the reverse geocoded location are returned in the
XandYoutput fields in thelocationobject of the JSON response.
Example
returnInputLocation=trueResponse status
| Status | Meaning | Description | Schema |
|---|---|---|---|
200 | OK | A successful response for a | Inline |
400 | Bad request | Invalid query parameters. Learn more in Service output. | |
403 | Forbidden | The required paramter | |
5 | Unknown | An error occured on the server. Learn more in Service output. |
Go to Service output for extended codes.
Response details
{
"address": {
"Match_addr": "<MatchAddress>",
"LongLabel": "<LongLabel>",
"ShortLabel": "<ShortLabel>",
"Addr_type": "<AddressType>",
"Type": "<Type>",
"PlaceName": "<PlaceName>",
"AddNum": "<AddressNumber>",
"Address": "<StreetAddress>",
"Block": "<Block>",
"Sector": "<Sector>",
"Neighborhood": "<Neighborhood>",
"District": "<District>",
"City": "<City>",
"MetroArea": "<MetroArea>",
"Subregion": "<Subregion>",
"Region": "<Region>",
"Territory": "<Territory>",
"Postal": "<PostalCode>",
"PostalExt": "<PostalExtension>",
"CountryCode": "<CountryCode>",
"StrucType": "<StructureType>",
"StrucDet": "<StructureDetails>"
},
"location": {
"x": "<longitude>",
"y": "<latitude>",
"spatialReference": {
"wkid": "<WKID>",
"latestWkid": "<LatestWkid>"
}
}
}Examples
Match to POI centroid returned
In this example, which corresponds to callout 1 in the graphic above, the input location is within the search tolerance of both POI and PointAddress features, but a match to the POI centroid is returned because it has a higher priority.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.205525,34.038232&token=<ACCESS_TOKEN>Match to POI area returned
In this example, which corresponds to callout 2 in the graphic above, the input location is within a POI area feature, so a POI match is returned.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.205525792308,34.037072461598&token=<ACCESS_TOKEN>StreetAddress match returned
In this example, which corresponds to callout 3 in the graphic above, the input location intersects a POI area feature and a StreetAddress buffer. A StreetAddress match is returned since it has a higher priority than POI areas. */}
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.20700637168703,34.03582108290202&token=<ACCESS_TOKEN>PointAddress match returned
In this example, which corresponds to callout 4 in the graphic above, the input location is within the search tolerance of a PointAddress feature, so a PointAddress match is returned.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.20689908332648,34.03431629224423&token=<ACCESS_TOKEN>Locality match returned
In this example, which corresponds to callout 5 in the graphic above, the input location is outside the tolerance of address and POI features, so the service returns a match to the smallest (by area) administrative or postal boundary feature that the location intersects. In this case, a match to the Live Oak Canyon neighborhood is returned.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.205794,34.035115&token=<ACCESS_TOKEN>StreetAddress match returned instead of StreetInt
In this example, which corresponds to callout 6 in the graphic above, the input location is within the tolerance of both StreetInt and StreetAddress features. Even though StreetInt has a higher priority than StreetAddress, a StreetAddress match is returned. This is because intersection matches are only returned by reverse if the request includes feature . The feature parameter is empty in this case.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.203741,34.036609&token=<ACCESS_TOKEN>Choose specific output features
The feature parameter can be used to specify one or more match types to be returned by a reverse request. If one value is included for feature , the search tolerance is extended to 500 meters. If the feature parameter includes multiple values, the search tolerances defined in the feature types hierarchy table are used. Details for the logic used by the feature parameter are described below.
The feature parameter affects geocoding results in the following ways:
-
If
featureis blank, the match is based on the default feature type hierarchy and search tolerances defined in the feature type hierarchy table, excluding StreetInt. StreetInt matches are only returned ifTypes featureis included in theTypes= Street Int reverserequest.Geocode -
If
featureincludes a single value, a search tolerance of 500 meters is used and only the input feature type is searched for.Types - If the input feature type exists within 500 meters of the input location, a match to that feature is returned.
- If there are no matches to the input feature type within 500 meters of the input location, no match is returned for the
reverserequest.Geocode
-
If
featureincludes multiple values, the default search tolerances for the input feature types as defined in the feature type hierarchy table are used to determine the match.Types - If the input location is within the search tolerance of only one of the input feature types, a match to that feature type is returned.
- If the input location is within the search tolerance of multiple input feature types, a match to the input feature type with the highest priority is returned.
- If the input location is not within the search tolerance of any of the input feature types, no match is returned.
Review the following examples to see how feature can be used in different scenarios.
Reverse geocode an intersection
In this example, you'll use the feature parameter to return a StreetInt match with a reverse request. This example uses the same input location as example 6 above.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=StreetInt&location=-117.203741,34.036609&token=<ACCESS_TOKEN>Reverse geocode a distant PointAddress
In this example, you'll use the feature parameter to return a match to a PointAddress feature when the input location is outside the default PointAddress search tolerance. Because Point is the only value included for the feature parameter in this reverse request, the search tolerance is 500 meters, which allows more distant PointAddress matches to be returned.
GET https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=PointAddress&location=-117.205958,34.035039&token=<ACCESS_TOKEN>Multiple input featureTypes values
A typical use case for the feature parameter is to exclude matches to nonaddress features, which can be accomplished by setting feature . In this example, the input location is within the search tolerance of both POI and PointAddress features, but a match to the PointAddress is returned because feature is used to exclude the POI match. This example uses the same input location as example 1 above.
GET https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=PointAddress,StreetAddress&location=-117.205453,34.037988&token=<ACCESS_TOKEN>Reverse geocode examples with langCode
Greek is the default language for features in Greece. However, many features are also available in English. This example shows how to return English reverse geocoding results for locations in Greece.
Reverse geocode a location with langCode=EN
GET https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&langCode=EN&location=23.73687,37.975252&token=<ACCESS_TOKEN>Reverse geocode a location with langCode=AR
In Israel, some addresses are available in both Hebrew and Arabic languages. Hebrew is the default language, so lang must be included in the reverse request to return matches in Arabic.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&langCode=AR&location=34.71402,31.79373&token=<ACCESS_TOKEN>Reverse geocode examples with the preferredLabelValues parameter
The preferred parameter allows limited customization of output values in reverse responses. Refer to the parameter overview for details about its functionality; this section includes examples showing how it can be used.
The preferred parameter can be used to override the default city name returned in output fields for a reverse geocoding transaction. The default values are based on country addressing conventions and data availability. United States addresses returned by the ArcGIS Geocoding service include the primary city name assigned to the postal code that is associated with the address; this is known as the postal city name. Sometimes the postal city name is different than the name of the city whose boundaries the address is within. For instance, one of the postal codes used in the city of Eagan, Minnesota, is 55123. The primary name assigned to postal code 55123 is Saint Paul, a city adjacent to Eagan. When addresses with postal code 55123 are reverse geocoded by the ArcGIS Geocoding service, the output labels and fields include Eagan as the city name by default.
Reverse geocode a location without preferredLabelValues .
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=PointAddress&preferredLabelValues=&location=-93.13726,44.803809&token=<ACCESS_TOKEN>Reverse geocode a location with preferredLabelValues=localCity
The preferred parameter can be used to return a more suitable city name for this address in reverse geocoding results. Pass preferred in the reverse request to return Eagan as the city name in the output.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=PointAddress&preferredLabelValues=localCity&location=-93.13726,44.803809&token=<ACCESS_TOKEN>Specify output fields
The reverse operation allows you to specify individual output fields or return all output fields. The out parameter is used for this. If you want to return all supported output fields, set out , or exclude the parameter from the request. By default, all output fields are returned for a reverse request, so passing out or out (blank) in the request, or excluding it altogether, produces the same results.
If your use case does not require all of the output fields to be returned, you can use the out parameter to specify a subset of output fields by passing the desired field names as comma-separated values in the request. For example, include out , to return the complete address, feature type, and country values for the reverse geocoded feature in the response.
See Service output for details about the fields returned by a reverse request.
The Input /Input output fields in the address object of the reverse JSON response always represent the coordinates that were passed in the request as the value for the location parameter. The X /Y output fields in the address object, on the other hand, always represent the coordinates of the feature returned by the reverse request.
Specify a subset of output fields for a PointAddress
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&location=4.937714,52.363908&featureTypes=PointAddress&outFields=LongLabel,Addr_type,CountryCode&token=<ACCESS_TOKEN>Return all output fields for a PointAddress
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&location=4.937714,52.363908&featureTypes=PointAddress&outFields=*&token=<ACCESS_TOKEN>Use input coordinates for output location
For some applications it may be useful to display the location of the input X/Y coordinates which were submitted in a reverse request as a point on a map. The return parameter is used for this.
The JSON response returned for a reverse request consists of two parts, with different purposes.
The location object includes information about the spatial reference and coordinates of the reverse request, which can be used for displaying the result on a map. The coordinates for display are defined by the x and y fields in this object.
location object
"location": {
"x": -117.195695233,
"y": 34.0560864,
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
}
}The address object includes details about the reverse result, such as the type of feature, its address, the city and country in which it's located, and other properties.
address object
"address": {
"Match_addr": "Esri",
"LongLabel": "Esri, 380 New York St, Redlands, CA, 92373, USA",
"ShortLabel": "Esri",
"Addr_type": "POI",
"Type": "Business Facility",
"PlaceName": "Esri",
"AddNum": "380",
"Address": "380 New York St",
"Block": "",
"Sector": "",
"Neighborhood": "West Redlands",
"District": "",
"City": "Redlands",
"MetroArea": "",
"Subregion": "San Bernardino County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Postal": "92373",
"PostalExt": "",
"CntryName": "United States",
"CountryCode": "USA",
"X": -117.195695233,
"Y": 34.0560864,
"InputX": -117.1959,
"InputY": 34.0561,
"StrucType": "",
"StrucDet": ""
}Notice that the address object also includes coordinate fields - X , Y , Input , and Input . The X and Y fields contain the coordinates of the feature returned by the reverse request. The Input , and Input fields contain the coordinates that were submitted in the reverse request for the input location parameter.
By default, the x and y fields in the location object of the response correspond to the location of the feature that is returned by the reverse request. If you want to display the input location on the map instead, include return in the reverse request. The return parameter only affects the values in the location object x and y fields; it does not modify the fields in the address object.
The example below illustrates how return can affect the output of a reverse request. In the image there are two points shown on a map.
- Point 1 represents the location of the coordinates passed as input in a
reverserequest. (x/y coordinates -117.1959,34.0561)Geocode - Point 2 represents the location of a POI in the geocoding service. (x/y coordinates -117.195695233,34.0560864)
If you pass the coordinates for point #1 as the location parameter in a reverse request, and also include return in the request, the point returned on the map in your application will correspond to the location of #1.
Using the same input location, if you exclude return from the request, then the point returned on the map will correspond to the location of #2.
Specify the input coordinates as the output location
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&returnInputLocation=true&location=-117.1959,34.0561&token=<ACCESS_TOKEN>Notice that the location object x and y values are the same as the Input and Input fields. This is because return was used in the request.