Reverse Geocode
- URL:https://<geocodeservice-url>/reverseGeocode
- Version Introduced:9.3
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.
New at 10.6
- The featureTypes parameter limits the possible match types performed by the reverseGeocode operation.
- The locationType parameter specifies that the output geometry of PointAddress matches should be the rooftop point or street entrance location.
New at 10.3
- The langCode parameter sets the language in which the geocode results are returned.
- The returnIntersection parameter indicates whether the service should return the nearest street intersection to the input location.
New at 10.0
- The outSR parameter specifies the well-known ID of the spatial reference or a spatial reference JSON object for the returned address candidates.
Request parameters
|
Parameter |
Details |
|---|---|
| location (Required) |
Defines an origin point that is used to boost search results for the closest address candidates based on their proximity to the location. The structure of the point can be represented as a simple comma-separated syntax (x,y) or as a JSON point object. If the comma-separated syntax is used, the spatial reference of the coordinates must be WGS84; otherwise, the spatial reference of the point coordinates can be defined in the JSON object. The location parameter can be used without specifying the distance parameter. If the distance is not specified, it defaults to 2000 meters. Example |
| 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. The spatial reference can be specified as either a well-known ID (WKID) or a JSON spatial reference object. If outSR is not specified, the spatial reference of the output location is the same as that of the service. For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems. Example |
| langCode (Optional) | Sets the language in which geocode results are returned. This is useful for ensuring that results are returned in the expected language. 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 components from the input search string. See the table of supported countries for more information and valid language code values in each country. Full language names cannot be used in the langCode parameter. Example |
| featureTypes (Optional) | Limits the possible match types performed by the reverseGeocode operation. If a single value is included, the search tolerance for the input feature type is 500 meters. If multiple values (separated by a comma, with no spaces) are included, the default search distances specified in the feature type hierarchy table are applied. Values: StreetInt | DistanceMarker | StreetAddress | StreetName | POI | PointAddress | Postal | Locality |
| returnIntersection (Optional) | Indicates whether the service returns the nearest street intersection to the input location. If true, the closest intersection to the input location is returned; if false (default), the closest address or place to the input location is returned. The returnIntersection parameter is only valid for geocode services that support intersections, which includes the IntersectionConnectors property in the service description.  Note:This parameter is only included for backward compatibility. Use the featureTypes parameter instead of returnIntersection. Specifically, to return the nearest street intersection to the input location, pass featureTypes=StreetInt in the reverseGeocode request. Values: true | false |
| locationType (Optional) | Specifies whether the rooftop point or street entrance is used as the output geometry of PointAddress matches. By default, street is used, which is useful in routing scenarios, as the rooftop location of some addresses may be offset from a street by a large distance. However, for map display purposes, you may want to use rooftop instead, especially when large buildings or landmarks are geocoded. The locationType parameter only affects the location object in the JSON response and does not change the x,y or DisplayX/DisplayY attribute values. Values: street | rooftop |
| distance (Optional) | Specifies the radius of an area (in meters) around a point location that is used to boost the rank of geocoding candidates so that candidates closest to the location are returned first. If this parameter is not provided, or an invalid value is given, a default value of 0 meters is used. If distance is specified, location must be specified as well. It is important to note that the location and distance parameters allow searches to extend beyond the specified search radius. They do not filter results as searchExtent does; they rank resulting candidates based on their distance from a location. Example |
| f (Required) | The response format. The default response format is html. Values: html | json | kmz |
Example usage
Reverse geocode based on a point:
JSON Response syntax
{
"address": {
"<fieldName1>": "<fieldValue1>",
"<fieldName2>": "<fieldValue2>"
}
"location": { <point> }
}
JSON Response example
{
"address": {
"Street": "771 TUNNEL AVE",
"Zone": "94005"
},
"location": {
"x": -122.400260954336,
"y": 37.7000445053795,
"spatialReference": {
"wkid": 4269
}
}
}