# How to use ReverseGeocode
This section contains a variety of how to guides and examples for how to use ReverseGeocode APIs.
**Topics**
+ [How to reverse geocode for a position](how-to-reverse-geocode-position.md)
+ [How to reverse geocode for correct result](reverse-geocode-filter-right-result.md)
+ [How to reverse geocode in a specific language](how-to-reverse-geocode-specific-language.md)
+ [How to reverse geocode for the time zone of a city](how-to-reverse-geocode-timezone.md)
+ [How to reverse geocode with a political view](reverse-geocode-political-view.md)
+ [How to get intersections](reverse-how-to-get-intersections.md)
# How to reverse geocode for a position
The Reverse Geocode API allows you to convert a geocode to a geographic area based on a position query. The API response includes place details, providing information about the location associated with specific coordinates.
## Potential use cases
+ **Store place information:** Add place details to a datastore containing geocoordinates.
+ **Map visualization:** Use place information to display data on a map.
+ **User location detection:** Identify the user's location based on their device position.
## Reverse geocode a position
------
#### [ Sample request ]
```
{
"QueryPosition": [
-123.11694,
49.28126
]
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointAddress",
"Title": "510 W Georgia St, Vancouver, BC V6B 0M3, Canada",
"Address": {
"Label": "510 W Georgia St, Vancouver, BC V6B 0M3, Canada",
"Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" },
"Region": { "Code": "BC", "Name": "British Columbia" },
"SubRegion": { "Name": "Metro Vancouver" },
"Locality": "Vancouver",
"District": "Downtown Vancouver",
"PostalCode": "V6B 0M3",
"Street": "W Georgia St",
"StreetComponents": [
{ "BaseName": "Georgia", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "W", "Language": "en" }
],
"AddressNumber": "510"
},
"Position": [-123.11694, 49.28126],
"Distance": 0,
"MapView": [-123.11813, 49.27786, -123.11076, 49.28246],
"AccessPoints": [
{ "Position": [-123.11656, 49.28151] }
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
-123.11694,
49.28126
]
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position "-123.11694,49.28126"
```
------
## Reverse geocode a position with multiple results
------
#### [ Sample request ]
```
{
"QueryPosition": [
-123.11694,
49.28126
],
"MaxResults": "3"
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointAddress",
"Title": "510 W Georgia St, Vancouver, BC V6B 0M3, Canada",
"Address": { /* Address details */ },
"Position": [-123.11694, 49.28126],
"Distance": 0,
"MapView": [/* Map view details */],
"AccessPoints": [/* Access point details */]
},
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "ChargePoint",
"Address": { /* Address details */ },
"Position": [-123.11663, 49.28116],
"Distance": 25,
"Categories": [/* Category details */],
"AccessPoints": [/* Access point details */]
},
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Zipcar",
"Address": { /* Address details */ },
"Position": [-123.11715, 49.28094],
"Distance": 29,
"Categories": [/* Category details */],
"AccessPoints": [/* Access point details */]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
-123.11694,
49.28126
],
"MaxResults": "3"
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position "-123.11694,49.28126" --max-results "3"
```
------
## Developer tips
For targeted results, use `IncludePlaceTypes` in the filter.
```
{
"QueryPosition": [
-123.11694,
49.28126
],
"Filter": { "IncludePlaceTypes": ["PointAddress"] }
}
```
# How to reverse geocode for correct result
This guide provides methods to refine reverse geocoding results, ensuring that the returned data aligns closely with specific business needs. Using filters, users can narrow down results to more precisely match types like address points, streets, or localities.
## Potential Use Cases
+ **Restrict results for specific needs:** Use filters to retrieve only the most relevant information, such as exact addresses or broader locality data, based on business requirements.
## Examples
### Filter for a Point Address
By filtering for `PointAddress`, you can retrieve specific street addresses, enhancing location accuracy.
------
#### [ Sample Request ]
```
{
"QueryPosition": [
-97.721, 30.404
],
"Filter": {
"IncludePlaceTypes": [
"PointAddress"
]
}
}
```
------
#### [ Sample Response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointAddress",
"Title": "11721 Domain Blvd, Austin, TX 78758-0051, United States",
"Address": {
"Label": "11721 Domain Blvd, Austin, TX 78758-0051, United States",
"Country": {
"Code2": "US",
"Code3": "USA",
"Name": "United States"
},
"Region": {
"Code": "TX",
"Name": "Texas"
},
"SubRegion": {
"Name": "Travis"
},
"Locality": "Austin",
"District": "North Burnet",
"PostalCode": "78758-0051",
"Street": "Domain Blvd",
"StreetComponents": [
{
"BaseName": "Domain",
"Type": "Blvd",
"TypePlacement": "AfterBaseName",
"TypeSeparator": " ",
"Language": "en"
}
],
"AddressNumber": "11721"
},
"Position": [
-97.72087,
30.404
],
"Distance": 5,
"MapView": [
-97.72219,
30.40273,
-97.72057,
30.40649
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"{
"QueryPosition": [
-97.721, 30.404
],
"Filter": {
"IncludePlaceTypes": [
"PointAddress"
]
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position -97.721 30.404 --filter '{"IncludePlaceTypes": ["PointAddress"]}'
```
------
### Filter for a Street
By filtering for `Street`, the API returns street-level data without specific address numbers.
------
#### [ Sample Request ]
```
{
"QueryPosition": [
-97.721, 30.404
],
"Filter": {
"IncludePlaceTypes": [
"Street"
]
}
}
```
------
#### [ Sample Response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "Street",
"Title": "Domain Blvd, Austin, TX 78758, United States",
"Address": {
"Label": "Domain Blvd, Austin, TX 78758, United States",
"Country": {
"Code2": "US",
"Code3": "USA",
"Name": "United States"
},
"Region": {
"Code": "TX",
"Name": "Texas"
},
"SubRegion": {
"Name": "Travis"
},
"Locality": "Austin",
"District": "North Burnet",
"PostalCode": "78758",
"Street": "Domain Blvd",
"StreetComponents": [
{
"BaseName": "Domain",
"Type": "Blvd",
"TypePlacement": "AfterBaseName",
"TypeSeparator": " ",
"Language": "en"
}
]
},
"Position": [
-97.72103,
30.40399
],
"Distance": 3,
"MapView": [
-97.72219,
30.40273,
-97.72057,
30.40649
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"{
"QueryPosition": [
-97.721, 30.404
],
"Filter": {
"IncludePlaceTypes": [
"Street"
]
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position -97.721 30.404 --filter '{"IncludePlaceTypes": ["Street"]}'
```
------
### Filter for a Locality
By filtering for `Locality`, you can retrieve broader location data, including city names.
------
#### [ Sample Request ]
```
{
"QueryPosition": [
-97.721, 30.404
],
"Filter": {
"IncludePlaceTypes": [
"Locality"
]
}
}
```
------
#### [ Sample Response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "Locality",
"Title": "Austin, TX, United States",
"Address": {
"Label": "Austin, TX, United States",
"Country": {
"Code2": "US",
"Code3": "USA",
"Name": "United States"
},
"Region": {
"Code": "TX",
"Name": "Texas"
},
"SubRegion": {
"Name": "Travis"
},
"Locality": "Austin",
"PostalCode": "78701"
},
"Position": [
-97.74299,
30.26759
],
"Distance": 0,
"MapView": [
-98.06484,
30.06592,
-97.55914,
30.51965
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"{
"QueryPosition": [
-97.721, 30.404
],
"Filter": {
"IncludePlaceTypes": [
"Locality"
]
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position -97.721 30.404 --filter '{"IncludePlaceTypes": ["Locality"]}'
```
------
# How to reverse geocode in a specific language
The feature allows the selection of a preferred response language from BCP47-compliant codes. It detects the query language based on name variants and uses the preferred language for unmatched tokens and ambiguous cases. If no requested language, the **Places** API provides results in the official country language, but prioritizes the regional language in regions where it differs. As a fallback strategy, if any address elements are unavailable in the requested language, **Places** APIs return addresses in the default language.
## Potential use cases
One potential use case is to localize the query and/or the result.
## Examples
### Get result in a specific language
------
#### [ Sample request ]
```
{
"QueryPosition": [
139.69172,
35.6895
],
"Language": "JA"
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointAddress",
"Title": "2-8-1 Nishishinjuku, Shinjuku-ku, Tokyo 160-0023, Japan",
"Address": {
"Label": "2-8-1 Nishishinjuku, Shinjuku-ku, Tokyo 160-0023, Japan",
"Country": {
"Code2": "JP",
"Code3": "JPN",
"Name": "Japan"
},
"Region": {
"Name": "Tokyo"
},
"SubRegion": {},
"Locality": "Shinjuku-ku",
"SubDistrict": "Nishishinjuku",
"PostalCode": "160-0023",
"Block": "2 Chome",
"SubBlock": "8",
"AddressNumber": "1"
},
"Position": [
139.69171,
35.68949
],
"Distance": 1,
"MapView": [
139.69071,
35.68861,
139.69251,
35.69048
],
"AccessPoints": [
{
"Position": [
139.69206,
35.68954
]
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
139.69172,
35.6895
],
"Language": "JA"
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position 139.69172 35.6895 --language "JA"
```
------
# How to reverse geocode for the time zone of a city
You can use the Reverse Geocode API to request for time zone information such as UTC offset and time zone name
## Potential use
Possible uses for geocode time zones:
+ Create a world clock
+ Schedule meetings in different geographies
## Examples
### Example
Reverse geocode a location in Tokyo, with time zone request.
------
#### [ Sample request ]
```
{
"QueryPosition": [
139.69172,
35.6895
],
"AdditionalFeatures": [
"TimeZone"
]
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointAddress",
"Title": "〒160-0023 東京都新宿区西新宿2丁目8-1",
"Address": {
"Label": "〒160-0023 東京都新宿区西新宿2丁目8-1",
"Country": {
"Code2": "JP",
"Code3": "JPN",
"Name": "日本"
},
"Region": {
"Name": "東京都"
},
"SubRegion": {},
"Locality": "新宿区",
"SubDistrict": "西新宿",
"PostalCode": "160-0023",
"Block": "2丁目",
"SubBlock": "8",
"AddressNumber": "1"
},
"Position": [
139.69171,
35.68949
],
"Distance": 1,
"MapView": [
139.69071,
35.68861,
139.69251,
35.69048
],
"AccessPoints": [
{
"Position": [
139.69206,
35.68954
]
}
],
"TimeZone": {
"Name": "Asia/Tokyo",
"Offset": "+09:00",
"OffsetSeconds": 32400
}
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
139.69172,
35.6895
],
"AdditionalFeatures": [
"TimeZone"
]
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position 139.69172 35.6895 --additional-features "TimeZone"
```
------
# How to reverse geocode with a political view
The Amazon Location Service allows you to specify a political view to ensure your application aligns with local regulations. This feature is useful when geocoding locations in disputed areas where place names or borders may vary depending on the political view.
## Potential Use Cases
**Adhere to local policies:** Ensure that place names and borders comply with legal requirements of the selected political view.
## Examples
### Reverse Geocode a Disputed Position
------
#### [ Sample Request ]
```
{
"QueryPosition": [
33.95876,
45.46824
],
"PoliticalView": "RUS"
}
```
------
#### [ Sample Response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "Locality",
"Title": "Первомайский район, Южный федеральный округ, Россия",
"Address": {
"Label": "Первомайский район, Южный федеральный округ, Россия",
"Country": {
"Code2": "RU",
"Code3": "RUS",
"Name": "Россия"
},
"Region": {
"Name": "Южный федеральный округ"
},
"SubRegion": {
"Name": "Республика Крым"
},
"Locality": "Первомайский район"
},
"Position": [
33.85939,
45.7142
],
"Distance": 0,
"MapView": [
33.52692,
45.34303,
34.12277,
45.80953
],
"PoliticalView": "RUS"
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
33.95876,
45.46824
],
"PoliticalView": "RUS"
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position 33.95876 45.46824 --political-view "RUS"
```
------
# How to get intersections
ReverseGeocode API can retrieve nearby intersections to the specified location.
## Potential use case
**Retrieve all nearby intersections. **This can be used by emergency services and delivery couriers. Emergency response vehicles often need to identify nearby intersections for optimal positioning when responding to calls. This allows them to maintain clear access routes and faster response times while ensuring visibility from multiple approaches. Similarly, delivery couriers can utilize intersection data to find more efficient parking spots, especially in dense urban areas where door-to-door parking may be limited or restricted.
## Get nearby intersections
Intersections are returned when the result type is Street, PointAddress, or InterpolatedAddress. To ensure you get nearby intersections, set the `Heading` parameter or filter for Street, PointAddress, or InterpolatedAddress types.
## Get nearby intersections with heading
------
#### [ Sample request ]
```
{
"QueryPosition": [-123.11694, 49.28126],
"AdditionalFeatures": ["Intersections"],
"Heading": 45
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointAddress",
"Title": "510 W Georgia St, Vancouver, BC V6B 0M3, Canada",
"Address": {
"Label": "510 W Georgia St, Vancouver, BC V6B 0M3, Canada",
"Country": {
"Code2": "CA",
"Code3": "CAN",
"Name": "Canada"
},
"Region": {
"Code": "BC",
"Name": "British Columbia"
},
"SubRegion": {
"Name": "Metro Vancouver"
},
"Locality": "Vancouver",
"District": "Downtown Vancouver",
"PostalCode": "V6B 0M3",
"Street": "W Georgia St",
"StreetComponents": [
{
"BaseName": "Georgia",
"Type": "St",
"TypePlacement": "AfterBaseName",
"TypeSeparator": " ",
"Prefix": "W",
"Language": "en"
}
],
"AddressNumber": "510"
},
"Position": [
-123.11694,
49.28126
],
"Distance": 0,
"MapView": [
-123.11813,
49.27786,
-123.11076,
49.28246
],
"Intersections": [
{
"PlaceId": "",
"Title": "W Georgia St & Richards St, Vancouver, BC V6B, Canada",
"Address": {
"Label": "W Georgia St & Richards St, Vancouver, BC V6B, Canada",
"PostalCode": "V6B",
"Intersection": [
"W Georgia St",
"Richards St"
]
},
"Position": [
-123.11614,
49.28124
],
"Distance": 58
},
{
"PlaceId": "",
"Title": "W Georgia St & Seymour St, Vancouver, BC V6B, Canada",
"Address": {
"Label": "W Georgia St & Seymour St, Vancouver, BC V6B, Canada",
"PostalCode": "V6B",
"Intersection": [
"W Georgia St",
"W Georgia St",
"Seymour St",
"Seymour St"
]
},
"Position": [
-123.11712,
49.28186
],
"Distance": 68
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
-123.11694, 49.28126
],
"AdditionalFeatures": ["Intersections"],
"Heading": 45
}
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position -123.11694, 49.28126 --additional-features "Intersections" --heading 45
```
------
## Get nearby intersections with street filter
------
#### [ Sample request ]
```
{
"QueryPosition": [-123.11694, 49.28126],
"AdditionalFeatures": ["Intersections"],
"Filter": {
"IncludePlaceTypes": ["Street"]
}
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "Street",
"Title": "W Georgia St, Vancouver, BC V6B, Canada",
"Address": {
"Label": "W Georgia St, Vancouver, BC V6B, Canada",
"Country": {
"Code2": "CA",
"Code3": "CAN",
"Name": "Canada"
},
"Region": {
"Code": "BC",
"Name": "British Columbia"
},
"SubRegion": {
"Name": "Metro Vancouver"
},
"Locality": "Vancouver",
"District": "Downtown Vancouver",
"PostalCode": "V6B",
"Street": "W Georgia St",
"StreetComponents": [
{
"BaseName": "Georgia",
"Type": "St",
"TypePlacement": "AfterBaseName",
"TypeSeparator": " ",
"Prefix": "W",
"Language": "en"
}
]
},
"Position": [
-123.11694,
49.28126
],
"Distance": 0,
"MapView": [
-123.11813,
49.27786,
-123.11076,
49.28246
],
"Intersections": [
{
"PlaceId": "",
"Title": "W Georgia St & Richards St, Vancouver, BC V6B, Canada",
"Address": {
"Label": "W Georgia St & Richards St, Vancouver, BC V6B, Canada",
"PostalCode": "V6B",
"Intersection": [
"W Georgia St",
"Richards St"
]
},
"Position": [
-123.11614,
49.28124
],
"Distance": 58
},
{
"PlaceId": "",
"Title": "W Georgia St & Seymour St, Vancouver, BC V6B, Canada",
"Address": {
"Label": "W Georgia St & Seymour St, Vancouver, BC V6B, Canada",
"PostalCode": "V6B",
"Intersection": [
"W Georgia St",
"W Georgia St",
"Seymour St",
"Seymour St"
]
},
"Position": [
-123.11712,
49.28186
],
"Distance": 68
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/reverse-geocode?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
-123.11694, 49.28126
],
"AdditionalFeatures": ["Intersections"],
"Filter": {
"IncludePlaceTypes": ["Street"]
}
}'
```
------
#### [ AWS CLI ]
```
aws geo-places reverse-geocode --key ${YourKey} --query-position -123.11694, 49.28126 --additional-features "Intersections" --filter '{"IncludePlaceTypes": ["Street"]}'
```
------