Reverse Geocode

Description

The reverseGeocode operation is performed on a geocode service resource. The result of this operation is a reverse-geocoded address resource. This resource provides information about all the address fields pertaining to the reverse-geocoded address as well as its exact location.

The reverseGeocode operation determines the address at a particular x/y location. You pass the coordinates of a point location to your geocoding service, and the service returns the address or place that is closest to the location.

NoteNote:

The REST request URL must include HTTPS. Requests with HTTP are not supported.

New at 10.6

New at 10.3

New at 10.0

Request parameters

Parameter

Details

location

(Required)

The point from which to search for the closest address or place. 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 by default the same as the data used to build the locator on which your geocoding service is based.

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

//simple syntax (with default WGS84 SR)
location=-117.196,34.056

//JSON (with default WGS84 SR)
location={x: 103.876722, y: 1.3330736}
token

(Required)

Specifies a token that provides the identity of a user who has the necessary permissions to access the service.

outSR

(Optional)

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 outSR is not specified, the spatial reference of the output locations is the same as that of the service. The default spatial reference of your geocoding service is always the same as the data used to build the locator on which your geocoding service is based.

For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.

Example

outSR=102100
langCode

(Optional)

Sets the language in which geocode results are returned. Addresses and places in many countries are available in more than one language; in these cases, the langCode parameter can be used to specify which language should be used for results returned by the findAddressCandidates operation. This is useful for ensuring that results are returned in the expected language. For example, a web application could be designed to get the browser language and pass it as the langCode parameter value in a findAddressCandidates request.

See the table of supported countries for valid language code values in each country. Full language names cannot be used in the langCode parameter. Only one language code value can be included for the langCode parameter in a findAddressCandidates request.

If the langCode 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 language code of the primary matched component from the input search string. Typically, this is either place-name or street name, depending on the search string.

It is important to note that langCode is limited by the address data sources used to build the locator for the geocoding service. This parameter will be ignored when not supported by the data.

Example

langCode=fr
featureTypes

(Optional)

Limits the possible match types returned by the reverseGeocode 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.

NoteNote:

Use featureTypes=StreetInt instead of the returnIntersection parameter to return intersection matches. Intersection matches are only returned when featureTypes=StreetInt is included in the request.

NoteNote:

The label for StreetAddress matches includes the house number range for the matching street segment, rather than the interpolated house number value. For instance, reverseGeocode with input location -117.196324,34.059217 returns a StreetAddress match with Match_addr=1001-1199 W Park Ave. This means that the matching segment has a possible range of house numbers from 1001 to 1199.

NoteNote:

If there are multiple Subaddress features with the same X/Y value intersected by a reverse geocode location, the label for a Subaddress candidate includes the range of unit numbers for all subaddress records in the stack. For instance, a reverseGeocode 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.

NoteNote:

If more than one value is specified for the parameter, the values must be separated by a comma, with no spaces after the comma.

Values: StreetInt | DistanceMarker | StreetAddress | StreetName | POI | Subaddress | PointAddress | Postal | Locality

Examples

//Single featureTypes value
featureTypes=PointAddress

//mMultiple featureTypes values
featureTypes=PointAddress,StreetAddress
returnIntersection

(Optional)

The returnIntersection parameter is only included for backward compatibility. The new featureTypes parameter should be used instead of returnIntersection. Specifically, if you want to return the nearest street intersection to the input location, pass featureTypes=StreetInt in the reverseGeocode 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.

NoteNote:

returnIntersection=true is equivalent to featureTypes=StreetInt in a reverseGeocode request.

Values: true | false

Example

returnIntersection=true
locationType

(Optional)

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) that 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 Addr_type=PointAddress or Subaddress, the X/Y attribute values describe the coordinates of the address along the street, while the DisplayX/DisplayY 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 locationType parameter can be used to specify that the street entrance geometry should be returned.

It is important to note that locationType is limited by the address data sources used to build the locator for the 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 locationType 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 locationType=street is requested.

NoteNote:

The locationType parameter only affects the location object in the geocode JSON response. It does not change the X/Y or DisplayX/DisplayY attribute values.

Values: street | rooftop

f

(Required)

The response format. The default response format is html.

Values: html | json| pjson | kmz

Reverse geocode details

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 reverseGeocode 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 findAddressCandidates can also be returned by reverseGeocode. As long as the location is within the extent of the data built to use the locator on which your geocoding service is based, 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.

NoteNote:

The label for StreetAddress matches includes the house number range for the matching street segment, rather than the interpolated house number value. For instance, a reverseGeocode with input location -117.196324,34.059217 returns a StreetAddress match with label 1001-1199 W Park Ave. This means that the matching segment has a possible range of house numbers from 1001 to 1199.

NoteNote:

If there are multiple Subaddress features with the same X/Y value intersected by a reverse geocode location, the label for a Subaddress candidate includes the range of unit numbers for all subaddress records in the stack. For instance, a reverseGeocode 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.

FeatureType

Search tolerance

Comments

StreetInt

10 meters

Intersections are only returned when featureTypes=StreetInt is included in the request.

StreetAddress (neara), DistanceMarker, or StreetName

3 meters

Candidates of type StreetName are only returned if featureTypes=StreetName is included in the request.

POI centroid

25 meters

A business or landmark that can be represented by a point.

Subaddress

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:

  1. The subaddress units cannot be collapsed into a contiguous range.
  2. The subaddresses have different street address, postal code, or administrative zone values.

PointAddress

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 featureTypes=StreetName is included in the request.

POI area

Within boundary

A business or landmark that can be represented by an area, such as a large park or university. This is not available unless supported by the data used to build the locator on which the geocode service is based.

Postal or Locality area

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 reverseGeocode 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.

Street map image showing location of reverse geocoding examples

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.

Features that can be reverse geocoded are highlighted.

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 reverseGeocode input locations. Refer to the following examples to see the expected matches for the input locations in the image.

Buffers illustrating the search tolerance of different feature types for reverse geocoding

For each number callout in the image above, there is a corresponding example with the same number.

Example input location 1: 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.

Request URL

https://[myServerURL]/arcgis/rest/services/[myGeocodeServiceName]/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.205416,34.038074

JSON response

{
 "address": {
  "Match_addr": "Premier ENT",
  "LongLabel": "Premier ENT, 255 Terracina Blvd, Redlands, CA, 92373, USA",
  "ShortLabel": "Premier ENT",
  "Addr_type": "POI",
  "Type": "Doctor",
  "PlaceName": "Premier ENT",
  "AddNum": "255",
  "Address": "255 Terracina Blvd",
  "Block": "",
  "Sector": "",
  "Neighborhood": "",
  "District": "",
  "City": "Redlands",
  "MetroArea": "",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "92373",
  "PostalExt": "",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.20541599999996,
  "y": 34.038074000000051,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

Example input location 2: 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.

Request URL

https://[myServerURL]/arcgis/rest/services/[myGeocodeServiceName]/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.20744088954731,34.0375903447169

JSON response

{
 "address": {
  "Match_addr": "Redlands Community Hospital",
  "LongLabel": "Redlands Community Hospital, 350 Terracina Blvd, Redlands, CA, 92373, USA",
  "ShortLabel": "Redlands Community Hospital",
  "Addr_type": "POI",
  "Type": "Hospital",
  "PlaceName": "Redlands Community Hospital",
  "AddNum": "350",
  "Address": "350 Terracina Blvd",
  "Block": "",
  "Sector": "",
  "Neighborhood": "Live Oak Canyon",
  "District": "",
  "City": "Redlands",
  "MetroArea": "Inland Empire",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "92373",
  "PostalExt": "",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.20744088954731,
  "y": 34.037590344716897,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

Example input location 3: 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.

Request URL

https://[myServerURL]/arcgis/rest/services/[myGeocodeServiceName]/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.20700637168703,34.03582108290202

JSON response

{
 "address": {
  "Match_addr": "1764-1792 W Fern Ave, Redlands, California, 92373",
  "LongLabel": "1764-1792 W Fern Ave, Redlands, CA, 92373, USA",
  "ShortLabel": "1764-1792 W Fern Ave",
  "Addr_type": "StreetAddress",
  "Type": "",
  "PlaceName": "",
  "AddNum": "1764",
  "Address": "1764 W Fern Ave",
  "Block": "",
  "Sector": "",
  "Neighborhood": "Live Oak Canyon",
  "District": "",
  "City": "Redlands",
  "MetroArea": "Inland Empire",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "92373",
  "PostalExt": "",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.20692023528862,
  "y": 34.03569657783153,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

Example input location 4: 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.

Request URL

https://[myServerURL]/arcgis/rest/services/[myGeocodeServiceName]/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.20689908332648,34.03431629224423

JSON response

{
 "address": {
  "Match_addr": "421 San Timoteo Canyon Rd, Redlands, California, 92373",
  "LongLabel": "421 San Timoteo Canyon Rd, Redlands, CA, 92373, USA",
  "ShortLabel": "421 San Timoteo Canyon Rd",
  "Addr_type": "PointAddress",
  "Type": "",
  "PlaceName": "",
  "AddNum": "421",
  "Address": "421 San Timoteo Canyon Rd",
  "Block": "",
  "Sector": "",
  "Neighborhood": "",
  "District": "",
  "City": "Redlands",
  "MetroArea": "",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "92373",
  "PostalExt": "7821",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.20737997312443,
  "y": 34.034238985755593,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

Example input location 5: 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.

Request URL

https://[myServerURL]/arcgis/rest/services/[myGeocodeServiceName]/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.205794,34.035115

JSON response

{
 "address": {
  "Match_addr": "Live Oak Canyon, Redlands, California",
  "LongLabel": "Live Oak Canyon, Redlands, CA, USA",
  "ShortLabel": "Live Oak Canyon",
  "Addr_type": "Locality",
  "Type": "Neighborhood",
  "PlaceName": "Live Oak Canyon",
  "AddNum": "",
  "Address": "",
  "Block": "",
  "Sector": "",
  "Neighborhood": "Live Oak Canyon",
  "District": "",
  "City": "Redlands",
  "MetroArea": "Inland Empire",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "",
  "PostalExt": "",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.205794,
  "y": 34.035114999999998,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

Example input location 6: StreetAddress match returned

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 reverseGeocode if the request includes featureTypes=StreetInt. The featureTypes parameter is empty in this case.

Request URL

https://[myServerURL]/arcgis/rest/services/[myGeocodeServiceName]/GeocodeServer/reverseGeocode?f=pjson&featureTypes=&location=-117.203741,34.036609

JSON response

{
 "address": {
  "Match_addr": "400-470 Terracina Blvd, Redlands, California, 92373",
  "LongLabel": "400-470 Terracina Blvd, Redlands, CA, 92373, USA",
  "ShortLabel": "400-470 Terracina Blvd",
  "Addr_type": "StreetAddress",
  "Type": "",
  "PlaceName": "",
  "AddNum": "402",
  "Address": "402 Terracina Blvd",
  "Block": "",
  "Sector": "",
  "Neighborhood": "Live Oak Canyon",
  "District": "",
  "City": "Redlands",
  "MetroArea": "Inland Empire",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "92373",
  "PostalExt": "",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.20378869939896,
  "y": 34.036582574473556,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

Choosing specific output features

Locators built with the Create Locator geoprocessing tool are configured to return the most relevant address or place for a given reverseGeocode input location. However, as a developer of an application that uses reverse geocoding, you may want to have more control over reverse geocode results. For instance, you may want users of your application to choose the features that are returned when they reverse geocode a location. Or perhaps the search tolerances mentioned in the previous table aren't sufficient and you want more distant addresses to be returned. Maybe you want to return StreetInt matches. You can use the featureTypes parameter to satisfy such requirements by refining reverse geocoding results.

The featureTypes parameter can be used to specify one or more match types to be returned by a reverseGeocode request. If one value is included for featureTypes, the search tolerance is extended to 500 meters. If the featureTypes parameter includes multiple values, the search tolerances defined in the feature types hierarchy table above are used. Details for the logic used by the featureTypes parameter are described below.

featureTypes match conditions

  • If featureTypes is 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 if featureTypes=StreetInt is included in the reverseGeocode request.
  • If featureTypes includes a single value, a search tolerance of 500 meters is used and only the input feature type is searched for.
    • 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 reverseGeocode request.
  • If featureTypes includes 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.
    • If the input location is within the search tolerance of only one of the input feature types, a match to that feature type is retuned.
    • 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.

featureTypes example: Reverse geocode an intersection

In this example, the featureTypes parameter is used to return a StreetInt match with a reverseGeocode request.

Request URL

https://[myServerURL]/arcgis/rest/services/[myGeocodeServiceName]/GeocodeServer/reverseGeocode?f=pjson&featureTypes=StreetInt&location=-117.203741,34.036609

JSON response

{
 "address": {
  "Match_addr": "W Fern Ave & Terracina Blvd, Redlands, California, 92373",
  "LongLabel": "W Fern Ave & Terracina Blvd, Redlands, CA, 92373, USA",
  "ShortLabel": "W Fern Ave & Terracina Blvd",
  "Addr_type": "StreetInt",
  "Type": "",
  "PlaceName": "",
  "AddNum": "",
  "Address": "W Fern Ave & Terracina Blvd",
  "Block": "",
  "Sector": "",
  "Neighborhood": "Live Oak Canyon",
  "District": "",
  "City": "Redlands",
  "MetroArea": "Inland Empire",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "92373",
  "PostalExt": "",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.20373988021336,
  "y": 34.036630049364923,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

featureTypes example: Multiple input featureTypes values

A typical use case for the featureTypes parameter is to exclude matches to non-address features, which can be accomplished by setting featureTypes=PointAddress,StreetAddress. 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 featureTypes is used to exclude the POI match.

NoteNote:

In this case, if featureTypes is not included in the request, a POI match is returned.

Request URL

https://[myServerURL]/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=pjson&featureTypes=PointAddress,StreetAddress&location=-117.205453,34.037988

{
 "address": {
  "Match_addr": "257 Terracina Blvd, Redlands, California, 92373",
  "LongLabel": "257 Terracina Blvd, Redlands, CA, 92373, USA",
  "ShortLabel": "257 Terracina Blvd",
  "Addr_type": "PointAddress",
  "Type": "",
  "PlaceName": "",
  "AddNum": "257",
  "Address": "257 Terracina Blvd",
  "Block": "",
  "Sector": "",
  "Neighborhood": "",
  "District": "",
  "City": "Redlands",
  "MetroArea": "",
  "Subregion": "San Bernardino County",
  "Region": "California",
  "Territory": "",
  "Postal": "92373",
  "PostalExt": "",
  "CountryCode": "USA"
 },
 "location": {
  "x": -117.20538197886449,
  "y": 34.038152999262394,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}