Reverse Geocode

(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 Using spatial references.

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

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

(Required)

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

(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 Using spatial references.

outSR=102100

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

langCode=fr

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

Note:

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.

Note:

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.

Note:

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.

Note:

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: Subaddress | PointAddress | Parcel |StreetAddress | StreetInt | StreetName | POI | DistanceMarker | Locality | Postal

//Single featureTypes value
featureTypes=PointAddress

//mMultiple featureTypes values
featureTypes=PointAddress,StreetAddress

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

Note:

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

Values: true | false

returnIntersection=true

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

Note:

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

(Required)

The response format. The default response format is html.

Values: html | json| pjson | kmz

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.