# How to use Geocode This section contains a variety of how to guides and examples for how to use Geocode APIs. **Topics** + [How to geocode an administrative and postal area](how-to-geocode-admin-postal-area.md) + [How to geocode an address](how-to-geocode-address.md) + [How to geocode a point of interest](how-to-geocode-poi.md) + [How to geocode an address number with a postal code](how-to-geocode-address-postal-code.md) + [How to geocode using geospatial context](how-to-geocode-geospatial.md) + [How to geocode using filters](how-to-geocode-filters.md) + [How to geocode for the time zone of a city](how-to-geocode-timezone.md) + [How to geocode in a specific language](how-to-geocode-specific-language.md) + [How to get secondary addresses](get-secondary-address.md) + [How to get intersections](get-intersections.md) # How to geocode an administrative and postal area The Geocode API allows you to perform geocoding for a geographic area using a query text input, such as the name of a country, region (state or province), or city. The API response includes location details like geographic coordinates, bounding boxes for map visualizations, and match scores indicating the result's relevance to the query. ## Potential use cases + **Obtain coordinates for an administrative area:** Use coordinates as a bias position or center in other Places APIs. + **Visualize information on a map:** Geocoded coordinates can be used to display data visually on a map. ## Examples ### Geocode a Country ------ #### [ Sample request ] ``` { "QueryText": "Canada" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId":"", "PlaceType": "Country", "Title": "Canada", "Address": { "Label": "Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" } }, "Position": [-75.69122, 45.42177], "MapView": [-141.00271, 41.67659, -52.61901, 83.11062], "MatchScores": { "Overall": 1, "Components": { "Address": { "Country": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "Canada" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourAPIKey} --query-text "Canada" ``` ------ ### Geocode a Region ------ #### [ Sample request ] ``` { "QueryText": "BC" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Region", "Title": "BC, Canada", "Address": { "Label": "BC, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" } }, "Position": [-123.36445, 48.42854], "MapView": [-139.04941, 48.22478, -114.05201, 60.00043], "MatchScores": { "Overall": 1, "Components": { "Address": { "Region": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "BC" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourAPIKey} --query-text "BC" ``` ------ ### Geocode a City ------ #### [ Sample request ] ``` { "QueryText": "Vancouver" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Locality", "Title": "Vancouver, BC, Canada", "Address": { "Label": "Vancouver, BC, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Vancouver", "PostalCode": "V5Y" }, "Position": [-123.11336, 49.26038], "MapView": [-123.26754, 49.19891, -123.02301, 49.33557], "MatchScores": { "Overall": 1, "Components": { "Address": { "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "Vancouver" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourAPIKey} --query-text "Vancouver" ``` ------ ### Geocode a Postal Code You can geocode a postal code. Use `IncludePlaceTypes` with `["PostalCode"]` for more precise results. ------ #### [ Sample request ] ``` { "QueryText": "800006", "Filter": { "IncludePlaceTypes": ["PostalCode"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PostalCodeArea", "Title": "800006, Patna, Bihar, India", "Address": { "Label": "800006, Patna, Bihar, India", "Country": { "Code2": "IN", "Code3": "IND", "Name": "India" }, "Region": { "Code": "BR", "Name": "Bihar" }, "SubRegion": { "Name": "Patna" }, "Locality": "Patna", "PostalCode": "800006" }, "Position": [85.18048, 25.61532], "MapView": [85.16599, 25.60054, 85.19103, 25.6221], "MatchScores": { "Overall": 1, "Components": { "Address": { "PostalCode": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "800006", "Filter": { "IncludePlaceTypes": ["PostalCode"] } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourAPIKey} --query-text "800006" --filter '{"IncludePlaceTypes": ["PostalCode"]}' ``` ------ ## Developer tips Use filters like `IncludeCountries` and `IncludePlaceTypes` for more targeted results. For example, to ensure results from Vancouver in the USA, set `"IncludeCountries": ["USA"]`. For more details, see . ``` { "QueryText": "Vancouver", "Filter": { "IncludeCountries": ["USA"] } } ``` # How to geocode an address The Geocode API enables you to geocode a specific point address, interpolated address, or street. The API response contains location information, including geographical coordinates and match scores that i ndicate how accurately the result aligns with the query. ## Potential use cases + **Clean address database:** Enhance data quality by identifying and correcting errors in address records. + **Normalize and standardize addresses:** Ensure consistent address formatting across datasets for improved data interoperability. + **Enrich addresses with additional information:** Add geographic coordinates and other relevant details to address records to support location-based analytics and insights. ## Examples ### Use query text ------ #### [ Sample request ] ``` { "QueryText": "510 W Georgia St, Vancouver, BC" } ``` ------ #### [ 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 ], "MapView": [ -123.11832, 49.28036, -123.11556, 49.28216 ], "AccessPoints": [ { "Position": [ -123.11656, 49.28151 ] } ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Region": 1, "Locality": 1, "Intersection": [ 1 ], "AddressNumber": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{"QueryText": "510 W Georgia St, Vancouver, BC"}' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourAPIKey} --query-text "510 W Georgia St, Vancouver, BC" ``` ------ ### Use query components ------ #### [ Sample request ] ``` { "QueryComponents": { "AddressNumber": "510", "Locality": "Vancouver", "Region": "BC", "Country": "Canada", "Street": "Georgia" } } ``` ------ #### [ 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 ], "MapView": [ -123.11832, 49.28036, -123.11556, 49.28216 ], "AccessPoints": [ { "Position": [ -123.11656, 49.28151 ] } ], "MatchScores": { "Overall": 0.99, "Components": { "Address": { "Country": 1, "Region": 1, "Locality": 1, "Intersection": [ 0.78 ], "AddressNumber": 1 } } } }, { "PlaceId": "", "PlaceType": "InterpolatedAddress", "Title": "510 E Georgia St, Vancouver, BC V6A 1Z9, Canada", "Address": { "Label": "510 E Georgia St, Vancouver, BC V6A 1Z9, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Vancouver", "District": "Strathcona", "PostalCode": "V6A 1Z9", "Street": "E Georgia St", "StreetComponents": [ { "BaseName": "Georgia", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "E", "Language": "en" } ], "AddressNumber": "510" }, "Position": [ -123.0932, 49.27829 ], "MapView": [ -123.09458, 49.27739, -123.09182, 49.27919 ], "AccessPoints": [ { "Position": [ -123.0932, 49.27842 ] } ], "MatchScores": { "Overall": 0.99, "Components": { "Address": { "Country": 1, "Region": 1, "Locality": 1, "Intersection": [ 0.78 ], "AddressNumber": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{"QueryComponents": {"AddressNumber": "510", "Locality": "Vancouver", "Region": "BC", "Country": "Canada", "Street": "Georgia"}}' ``` ------ #### [ AWS CLI ] ``` ./aws geo-places geocode --key ${YourAPIKey} --query-components '{ "AddressNumber" : "510", "Locality": "vancouver", "Region": "BC", "Country": "Canada", "Street": "Georgia"}' ``` ------ ### Use hybrid query ------ #### [ Sample request ] ``` { "QueryText": "W. 6th St", "QueryComponents": { "AddressNumber": "415", "Locality": "Vancouver" } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointAddress", "Title": "415 W 6th St, Vancouver, WA 98660-3375, United States", "Address": { "Label": "415 W 6th St, Vancouver, WA 98660-3375, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Esther Short", "PostalCode": "98660-3375", "Street": "W 6th St", "StreetComponents": [ { "BaseName": "6th", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "W", "Language": "en" } ], "AddressNumber": "415" }, "Position": [ -122.67543, 45.62527 ], "MapView": [ -122.67672, 45.62437, -122.67414, 45.62617 ], "AccessPoints": [ { "Position": [ -122.67543, 45.62506 ] } ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Locality": 1, "Intersection": [ 1 ], "AddressNumber": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{"QueryText": "W. 6th St", "QueryComponents": {"AddressNumber": "415", "Locality": "Vancouver"}}' ``` ------ #### [ AWS CLI ] ``` ./aws geo-places geocode -key ${YourAPIKey} --query-text "W. 6th St" \ --query-components '{"AddressNumber" : "415", "Locality": "Vancouver"}' ``` ------ ## Developer Tips Use filters like `IncludeCountries` and `IncludePlaceTypes` to obtain accurate results. For instance, if you need Vancouver from the USA, apply `"IncludeCountries": ["USA"]` to prioritize results in the USA. To learn more, see [How to geocode using filters](how-to-geocode-filters.md). ``` { "QueryText": "Vancouver", "Filter": { "IncludeCountries": ["USA"], "IncludePlaceTypes": ["City"] } } ``` # How to geocode a point of interest You can use the geocode API to geocode the coordinates of a known place (Point of interest) such as business addresses, landmark, or tourist spot. The API response contains location information, including geographical coordinates, and match scores that indicate how well the result matches the query. ## Potential use cases + Provide geographical coordinates that correspond to points of interest enhances the user experience + Provide geographical coordinates that correspond to points of interest can optimize logistics ## Examples ### Geocode a business ------ #### [ Sample request ] ``` { "QueryText": "Starbucks , Vancouver" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 1099 Robson St, Vancouver, BC V6E 1A9, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Vancouver", "District": "West End", "PostalCode": "V6E 1A9", "Street": "Robson St", "StreetComponents": [ { "BaseName": "Robson", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "1099" }, "Position": [ -123.12454, 49.28462 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -123.12463, 49.28447 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 980 Seymour St, Vancouver, BC V6B 1B5, 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 1B5", "Street": "Seymour St", "StreetComponents": [ { "BaseName": "Seymour", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "980" }, "Position": [ -123.12142, 49.2786 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -123.12185, 49.27873 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 918 SE 164th Ave, Vancouver, WA 98683-9603, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Cascade Highlands", "PostalCode": "98683-9603", "Street": "SE 164th Ave", "StreetComponents": [ { "BaseName": "164th", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "SE", "Language": "en" } ], "AddressNumber": "918" }, "Position": [ -122.50495, 45.61409 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.50493, 45.61401 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 304 W 8th St, Vancouver, WA 98660-3112, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Esther Short", "PostalCode": "98660-3112", "Street": "W 8th St", "StreetComponents": [ { "BaseName": "8th", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "W", "Language": "en" } ], "AddressNumber": "304" }, "Position": [ -122.67418, 45.6274 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.67419, 45.62725 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 3707 Main St, Vancouver, WA 98663-2227, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Shumway", "PostalCode": "98663-2227", "Street": "Main St", "StreetComponents": [ { "BaseName": "Main", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "3707" }, "Position": [ -122.667, 45.64849 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.66705, 45.64849 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 2811 E Fourth Plain Blvd, Vancouver, WA 98661, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Rose Village", "PostalCode": "98661", "Street": "E Fourth Plain Blvd", "StreetComponents": [ { "BaseName": "Fourth Plain", "Type": "Blvd", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "E", "Language": "en" } ], "AddressNumber": "2811" }, "Position": [ -122.64149, 45.63818 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.64185, 45.63828 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 2500 Columbia House Blvd, Vancouver, WA 98661-7758, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Hudson Bay", "PostalCode": "98661-7758", "Street": "Columbia House Blvd", "StreetComponents": [ { "BaseName": "Columbia House", "Type": "Blvd", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "2500" }, "Position": [ -122.64584, 45.62036 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.64584, 45.61986 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 8801 NE Hazel Dell Ave, Vancouver, WA 98665-8145, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Northeast Hazel Dell-Starcrest", "PostalCode": "98665-8145", "Street": "NE Hazel Dell Ave", "StreetComponents": [ { "BaseName": "Hazel Dell", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "8801" }, "Position": [ -122.66834, 45.68623 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.66834, 45.68641 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 7720 NE Highway 99, Vancouver, WA 98665, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Northeast Hazel Dell", "PostalCode": "98665", "Street": "NE Highway 99", "StreetComponents": [ { "BaseName": "Highway 99", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "7720" }, "Position": [ -122.66264, 45.67787 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.66293, 45.67793 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 408 NE 81st St, Vancouver, WA 98665-8111, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Northeast Hazel Dell-Starcrest", "PostalCode": "98665-8111", "Street": "NE 81st St", "StreetComponents": [ { "BaseName": "81st", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "408" }, "Position": [ -122.66824, 45.68161 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.66824, 45.68138 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 6701 E Mill Plain Blvd, Vancouver, WA 98661-7459, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Vancouver Heights", "PostalCode": "98661-7459", "Street": "E Mill Plain Blvd", "StreetComponents": [ { "BaseName": "Mill Plain", "Type": "Blvd", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "E", "Language": "en" } ], "AddressNumber": "6701" }, "Position": [ -122.6031, 45.62623 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.6031, 45.62635 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 8700 NE Vancouver Mall Dr, Vancouver, WA 98662-6416, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "PostalCode": "98662-6416", "Street": "NE Vancouver Mall Dr", "StreetComponents": [ { "BaseName": "Vancouver Mall", "Type": "Dr", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "8700" }, "Position": [ -122.58543, 45.65786 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.58512, 45.65739 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 8302 E Mill Plain Blvd, Vancouver, WA 98664-2007, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "North Garrison Heights", "PostalCode": "98664-2007", "Street": "E Mill Plain Blvd", "StreetComponents": [ { "BaseName": "Mill Plain", "Type": "Blvd", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "E", "Language": "en" } ], "AddressNumber": "8302" }, "Position": [ -122.58719, 45.62393 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.58712, 45.62393 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 7809 NE Vancouver Plaza Dr, Vancouver, WA 98662-6624, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Ogden", "PostalCode": "98662-6624", "Street": "NE Vancouver Plaza Dr", "StreetComponents": [ { "BaseName": "Vancouver Plaza", "Type": "Dr", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "7809" }, "Position": [ -122.5919, 45.65126 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.59217, 45.65112 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 2615 NE 112th Ave, Vancouver, WA 98684-4283, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Landover-Sharmel", "PostalCode": "98684-4283", "Street": "NE 112th Ave", "StreetComponents": [ { "BaseName": "112th", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "2615" }, "Position": [ -122.55675, 45.64148 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.55675, 45.64157 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 13719 SE Mill Plain Blvd, Vancouver, WA 98684-6945, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Mountain View", "PostalCode": "98684-6945", "Street": "SE Mill Plain Blvd", "StreetComponents": [ { "BaseName": "Mill Plain", "Type": "Blvd", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "SE", "Language": "en" } ], "AddressNumber": "13719" }, "Position": [ -122.53093, 45.61691 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.53093, 45.61714 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 6711 NE 63rd St, Vancouver, WA 98661-1997, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Walnut Grove", "PostalCode": "98661-1997", "Street": "NE 63rd St", "StreetComponents": [ { "BaseName": "63rd", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "6711" }, "Position": [ -122.60365, 45.66671 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.60365, 45.66679 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 8720 NE Centerpointe Dr, Vancouver, WA 98665-1153, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Sunnyside-Walnut Grove", "PostalCode": "98665-1153", "Street": "NE Centerpointe Dr", "StreetComponents": [ { "BaseName": "Centerpointe", "Type": "Dr", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "8720" }, "Position": [ -122.6019, 45.68537 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.60189, 45.6852 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 7411 NE 117th Ave, Vancouver, WA 98662-4705, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Orchards Area", "PostalCode": "98662-4705", "Street": "NE 117th Ave", "StreetComponents": [ { "BaseName": "117th", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "7411" }, "Position": [ -122.55103, 45.67666 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.55103, 45.67684 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "STARBUCKS", "Address": { "Label": "STARBUCKS, 11211 NE Fourth Plain Blvd, Vancouver, WA 98662-5770, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "District": "Orchards Area", "PostalCode": "98662-5770", "Street": "NE Fourth Plain Blvd", "StreetComponents": [ { "BaseName": "Fourth Plain", "Type": "Blvd", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "NE", "Language": "en" } ], "AddressNumber": "11211" }, "Position": [ -122.5575, 45.66574 ], "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Coffee Shop", "Primary": true } ], "AccessPoints": [ { "Position": [ -122.55751, 45.66587 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "Starbucks , Vancouver" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "Starbucks , Vancouver" ``` ------ ### Geocode a tourist spot ------ #### [ Sample request ] ``` { "QueryText": "Eiffel Tower, Paris" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "The Eiffel Tower Romance", "Address": { "Label": "The Eiffel Tower Romance, Rue de Rivoli, 75004 Paris, France", "Country": { "Code2": "FR", "Code3": "FRA", "Name": "France" }, "Region": { "Code": "IDF", "Name": "Île-de-France" }, "SubRegion": { "Name": "Paris" }, "Locality": "Paris", "District": "4e Arrondissement", "PostalCode": "75004", "Street": "Rue de Rivoli", "StreetComponents": [ { "BaseName": "Rivoli", "Type": "Rue de", "TypePlacement": "BeforeBaseName", "TypeSeparator": " ", "Language": "fr" } ] }, "Position": [ 2.35284, 48.85702 ], "Categories": [ { "Id": "theatre,_music_and_culture", "Name": "Theatre, Music and Culture", "LocalizedName": "Théâtre, musique et culture", "Primary": true }, { "Id": "historical_monument", "Name": "Historical Monument", "LocalizedName": "Monument historique", "Primary": false } ], "AccessPoints": [ { "Position": [ 2.3529, 48.85714 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Eiffel Tower", "Address": { "Label": "Eiffel Tower, 2025 S Collegiate Dr, Paris, TX 75460-7853, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "TX", "Name": "Texas" }, "SubRegion": { "Name": "Lamar" }, "Locality": "Paris", "PostalCode": "75460-7853", "Street": "S Collegiate Dr", "StreetComponents": [ { "BaseName": "Collegiate", "Type": "Dr", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "S", "Language": "en" } ], "AddressNumber": "2025" }, "Position": [ -95.52403, 33.64055 ], "Categories": [ { "Id": "historical_monument", "Name": "Historical Monument", "LocalizedName": "Historical Monument", "Primary": true }, { "Id": "landmark-attraction", "Name": "Landmark-Attraction", "LocalizedName": "Landmark-Attraction", "Primary": false } ], "AccessPoints": [ { "Position": [ -95.52411, 33.6405 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Eiffel Tower", "Address": { "Label": "Eiffel Tower, Northland Dr, Paris, MI 49338, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "MI", "Name": "Michigan" }, "SubRegion": { "Name": "Mecosta" }, "Locality": "Paris", "PostalCode": "49338", "Street": "Northland Dr", "StreetComponents": [ { "BaseName": "Northland", "Type": "Dr", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ] }, "Position": [ -85.50268, 43.78907 ], "Categories": [ { "Id": "outdoor-recreation", "Name": "Outdoor-Recreation", "LocalizedName": "Outdoor/Recreation", "Primary": true } ], "AccessPoints": [ { "Position": [ -85.50282, 43.78907 ] } ], "MatchScores": { "Overall": 1, "Components": { "Title": 1, "Address": { "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "Eiffel Tower, Paris" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "Eiffel Tower, Paris" ``` ------ ## Developer tips + Use complete addresses or query component for better results. To learn more, see [How to geocode an address](how-to-geocode-address.md). + Use filters like `IncludeCountries` and `IncludePlaceTypes` to obtain accurate results. For instance, if you need Vancouver from the USA, apply `"IncludeCountries": ["USA"]` to prioritize results in the USA. To learn more, see [How to geocode using filters](how-to-geocode-filters.md). ``` { "QueryText": "Vancouver", "Filter": { "IncludeCountries": ["USA"], "IncludePlaceTypes": ["City"] } } ``` # How to geocode an address number with a postal code In countries where postal codes are highly specific (linking only a few addresses on the same street), an address can be found using only the house number and postal code. This practice is common in transportation and parcel delivery logistics. This feature is supported in Canada, the United Kingdom, the Netherlands, the United States (ZIP\$14), Israel, Ireland, and Singapore. In both Ireland and Singapore, postal codes provide exact location details down to the specific house number. ## Examples ### Geocode an address with postal code ------ #### [ Sample request ] Use query component ``` { "QueryComponents": { "AddressNumber": "1368", "PostalCode": "V5N 1T2" } } ``` Use free text ``` { "QueryText": "1368, V5N1T2" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointAddress", "Title": "1368 E 8th Ave, Vancouver, BC V5N 1T2, Canada", "Address": { "Label": "1368 E 8th Ave, Vancouver, BC V5N 1T2, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Vancouver", "District": "Grandview-Woodland", "PostalCode": "V5N 1T2", "Street": "E 8th Ave", "StreetComponents": [ { "BaseName": "8th", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Prefix": "E", "Language": "en" } ], "AddressNumber": "1368" }, "Position": [ -123.07612, 49.26306 ], "MapView": [ -123.0775, 49.26216, -123.07474, 49.26396 ], "AccessPoints": [ { "Position": [ -123.07611, 49.26333 ] } ], "MatchScores": { "Overall": 1, "Components": { "Address": { "PostalCode": 1, "AddressNumber": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryComponents": { "AddressNumber": "1368", "PostalCode": "V5N 1T2" } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-components '{"AddressNumber" : "1368", "PostalCode": "V5N 1T2"}' ``` ------ ### Geocode an address with postal code in Singapore and Ireland In Ireland, the Eircode system assigns a unique code to every home and business, while in Singapore, postal codes are equally specific. In both countries, a postal code alone can identify an exact address: there is no need for the street name, city, or house number. + Singapore: 6-digit postal code + Ireland: 7-character Eircode ------ #### [ Sample request ] Use query component ``` { "QueryComponents": { "PostalCode": "D02 X285" } } ``` Use free text ``` { "QueryText": "D02 X285" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointAddress", "Title": "29-31 Adelaide Road, Dublin, County Dublin, D02 X285, Ireland", "Address": { "Label": "29-31 Adelaide Road, Dublin, County Dublin, D02 X285, Ireland", "Country": { "Code2": "IE", "Code3": "IRL", "Name": "Ireland" }, "SubRegion": { "Code": "D", "Name": "County Dublin" }, "Locality": "Dublin", "District": "Dublin 2", "PostalCode": "D02 X285", "Street": "Adelaide Road", "StreetComponents": [ { "BaseName": "Adelaide", "Type": "Road", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "29-31" }, "Position": [ -6.25549, 53.33207 ], "MapView": [ -6.257, 53.33117, -6.25398, 53.33297 ], "AccessPoints": [ { "Position": [ -6.25536, 53.33231 ] } ], "MatchScores": { "Overall": 1, "Components": { "Address": { "PostalCode": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryComponents": { "PostalCode": "D02 X285" } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-components '{"PostalCode": "V5N 1T2"}' ``` ------ ## Developer tips Learn more about [ZIP\$14](https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4) (United States) and [ Eircode](https://en.wikipedia.org/wiki/Postal_addresses_in_the_Republic_of_Ireland) (Ireland). Also, learn about postal code system in Canada, the United Kingdom, the Netherlands, Singapore, and Israel. # How to geocode using geospatial context The Geocode API enables you to use geospatial context (such as bias position) to get desired results. **Note** "Bias position" refers to a mechanism that prioritizes search results based on a user's specified location or a defined area. It essentially shifts the focus of search results towards locations that are geographically closer to a designated bias point, without necessarily excluding other results. ## Potential use Use geospatial context to get the correct results based on your business needs. ## Examples ### Bias results to a position By biasing to a position, you can change the rankings of your results. Try the following example, with— and then without—the `BiasPosition` value and compare the results. ------ #### [ Sample request ] ``` { "QueryText": "George Street", "BiasPosition": [ 151.2059, -33.8691 ] } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Street", "Title": "George St, Sydney NSW, Australia", "Address": { "Label": "George St, Sydney NSW, Australia", "Country": { "Code2": "AU", "Code3": "AUS", "Name": "Australia" }, "Region": { "Code": "NSW", "Name": "New South Wales" }, "Locality": "Sydney", "Street": "George St", "StreetComponents": [ { "BaseName": "George", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ] }, "Position": [ 151.20691, -33.86974 ], "Distance": 117, "MapView": [ 151.20225, -33.88406, 151.20912, -33.85635 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Intersection": [ 1 ] } } } }, ... ... ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "George Street", "BiasPosition": [ 151.2059, -33.8691 ] }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "George Street" --bias-position 151.2059 -33.8691 ``` ------ ## Developer tips For address geocoding, try to use complete addresses or a query component with a combination of bias position, including country and place. To learn more, see [How to geocode an address](how-to-geocode-address.md). # How to geocode using filters The Geocode API enables you to use filters to get desired results. ## Potential use Use filters to restrict results based on your business needs. ## Examples ### Limit results within a country Specify a value for `IncludeCountries` to return values for that country in the results. ------ #### [ Sample request ] Without `IncludeCountries": ["USA"]`, the Geocode API will return Vancouver, BC, Canada. ``` { "QueryText": "Vancouver", "Filter" : { "IncludeCountries": ["USA"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Locality", "Title": "Vancouver, WA, United States", "Address": { "Label": "Vancouver, WA, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Clark" }, "Locality": "Vancouver", "PostalCode": "98660" }, "Position": [ -122.67156, 45.63248 ], "MapView": [ -122.77466, 45.57714, -122.46451, 45.69803 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "Vancouver", "Filter" : { "IncludeCountries": ["USA"] } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "Vancouver" --filter '{"IncludeCountries": ["USA"]}' ``` ------ ### Refine results with place type filters Specify a value for `IncludePlaceTypes` to return values for that place in the results. ------ #### [ Sample request ] Without `IncludePlaceTypes": ["Street"]`, the Geocode API will return Georgia, a country. You can further refine the results by adding `"IncludeCountries"` with values of **CAN** and **USA** and compare the results. ``` { "QueryText": "Georgia", "Filter" : { "IncludePlaceTypes": ["Street"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Street", "Title": "Georgia, Benito Juárez, CDMX, México", "Address": { "Label": "Georgia, Benito Juárez, CDMX, México", "Country": { "Code2": "MX", "Code3": "MEX", "Name": "México" }, "Region": { "Code": "CDMX", "Name": "Ciudad de México" }, "SubRegion": { "Name": "Ciudad de México" }, "Locality": "Benito Juárez", "Street": "Georgia", "StreetComponents": [ { "BaseName": "Georgia", "Language": "es" } ] }, "Position": [ -99.17754, 19.38887 ], "MapView": [ -99.18133, 19.38755, -99.17374, 19.39016 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Intersection": [ 1 ] } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "Georgia", "Filter" : { "IncludePlaceTypes": ["Street"] } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "Georgia" --filter '{"IncludePlaceTypes": ["Street"]}' ``` ------ ## Developer tips For address geocoding, try to use complete addresses or a query component with a combination of bias position, including country and place. To learn more, see [How to geocode an address](how-to-geocode-address.md). # How to geocode for the time zone of a city You can use the Geocode API to provide 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 Geocode in Brussels, with time zone request. ------ #### [ Sample request ] ``` { "QueryText": "Brussels", "Filter" : { "IncludePlaceTypes": ["Locality"] }, "AdditionalFeatures": [ "TimeZone" ] } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Locality", "Title": "Brussel, België", "Address": { "Label": "Brussel, België", "Country": { "Code2": "BE", "Code3": "BEL", "Name": "België" }, "Region": { "Code": "BRU", "Name": "Brussel" }, "SubRegion": { "Name": "Brussel" }, "Locality": "Brussel", "PostalCode": "1000" }, "Position": [ 4.35609, 50.84439 ], "MapView": [ 4.3139, 50.79628, 4.43709, 50.91397 ], "TimeZone": { "Name": "Europe/Brussels", "Offset": "+02:00", "OffsetSeconds": 7200 }, "MatchScores": { "Overall": 1, "Components": { "Address": { "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText": "Brussels", "Filter" : { "IncludePlaceTypes": ["Locality"] }, "AdditionalFeatures": [ "TimeZone" ] }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "Brussels" \ --filter '{"IncludePlaceTypes": ["Locality"]}' \ --additional-features "TimeZone" ``` ------ # How to geocode in a specific language This 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 there is 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 ] ``` { "QueryText":"Patna, Bihar, Bharat", "Language": "HI" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Locality", "Title": "पटना, बिहार, भारत", "Address": { "Label": "पटना, बिहार, भारत", "Country": { "Code2": "IN", "Code3": "IND", "Name": "भारत" }, "Region": { "Code": "BR", "Name": "बिहार" }, "SubRegion": { "Name": "पटना" }, "Locality": "पटना", "PostalCode": "800001" }, "Position": [ 85.13752, 25.60134 ], "MapView": [ 85.03222, 25.55157, 85.27107, 25.65917 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Country": 1, "Region": 1, "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText":"Patna, Bihar, Bharat", "Language": "HI" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "पटना, बिहार, भारत" --language "HI" ``` ------ ### Query in a specific language ------ #### [ Sample request ] ``` { "QueryText":"पटना, बिहार, भारत" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Locality", "Title": "Patana, Bihar, Bharat", "Address": { "Label": "Patana, Bihar, Bharat", "Country": { "Code2": "IN", "Code3": "IND", "Name": "Bharat" }, "Region": { "Code": "BR", "Name": "Bihar" }, "SubRegion": { "Name": "Patana" }, "Locality": "Patana", "PostalCode": "800001" }, "Position": [ 85.13752, 25.60134 ], "MapView": [ 85.03222, 25.55157, 85.27107, 25.65917 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Country": 1, "Region": 1, "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText":"पटना, बिहार, भारत" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "पटना, बिहार, भारत" ``` ------ ### Query and result in a specific language ------ #### [ Sample request ] ``` { "QueryText":"पटना, बिहार, भारत", "Language": "HI" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "Locality", "Title": "पटना, बिहार, भारत", "Address": { "Label": "पटना, बिहार, भारत", "Country": { "Code2": "IN", "Code3": "IND", "Name": "भारत" }, "Region": { "Code": "BR", "Name": "बिहार" }, "SubRegion": { "Name": "पटना" }, "Locality": "पटना", "PostalCode": "800001" }, "Position": [ 85.13752, 25.60134 ], "MapView": [ 85.03222, 25.55157, 85.27107, 25.65917 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Country": 1, "Region": 1, "Locality": 1 } } } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText":"पटना, बिहार, भारत", "Language": "HI" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "पटना, बिहार, भारत" --language "HI" ``` ------ # How to get secondary addresses `SecondaryAddresses` allows you to retrieve all secondary addresses that are under a main address. Additionally, `Geocode` also returns secondary units, if any are present within the `QueryText`. A result item with a place type of `InferredSecondaryAddress` may be returned if there is parsed query support, `ParsedQuery.Address.SecondaryAddressComponents`, for that country. `InferredSecondaryAddress` results are returned based on provided data in the query. ## Potential use cases + **Address form completion:** To select a more accurate secondary address, which also includes more accurate positional information. + **Deliveries:** For countries that lack secondary address coverage, this information can help inform deliveries by including all provided unit information. ## Examples ### Get secondary addresses **Note** Coverage for `Address.SecondaryAddressComponents` is available in the following countries: AUS, CAN, NZL, USA, PRI Coverage for `ParsedQuery.Address.SecondaryAddressComponents` is available in the following countries: AUS, AUT, BRA, CAN, ESP, FRA, GBR, HKG, IDN, IND, NZL, TUR, TWN, USA ------ #### [ Sample request ] ``` { "QueryText":"910 Beach Avenue, Vancouver", "AdditionalFeatures": ["SecondaryAddresses"] } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointAddress", "Title": "910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Address": { "Label": "910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Vancouver", "District": "Downtown Vancouver", "PostalCode": "V6Z 2W7", "Street": "Beach Ave", "StreetComponents": [ { "BaseName": "Beach", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "910" }, "Position": [ -123.13325, 49.27542 ], "MapView": [ -123.13463, 49.27452, -123.13187, 49.27632 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Locality": 1, "Intersection": [ 1 ], "AddressNumber": 1 } } }, "ParsedQuery": { "Address": { "Locality": [ { "StartIndex": 18, "EndIndex": 27, "Value": "Vancouver", "QueryComponent": "Query" } ], "Street": [ { "StartIndex": 4, "EndIndex": 16, "Value": "Beach Avenue", "QueryComponent": "Query" } ], "AddressNumber": [ { "StartIndex": 0, "EndIndex": 3, "Value": "910", "QueryComponent": "Query" } ] } }, "SecondaryAddresses": [ { "PlaceId": "", "PlaceType": "SecondaryAddress", "Title": "101-910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Address": { "Label": "101-910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "SecondaryAddressComponents": [ { "Number": "101" } ] }, "Position": [ -123.1334, 49.27532 ] }, { "PlaceId": "", "PlaceType": "SecondaryAddress", "Title": "102-910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Address": { "Label": "102-910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "SecondaryAddressComponents": [ { "Number": "102" } ] }, "Position": [ -123.1334, 49.27532 ] }, ... ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText":"910 Beach Avenue, Vancouver", "AdditionalFeatures": ["SecondaryAddresses"] }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "910 Beach Avenue, Vancouver" --additional-features "SecondaryAddresses" ``` ------ ### Get secondary units provided in an address Coverage for this functionality is available in the following countries: AUS, AUT, BRA, CAN, ESP, FRA, GBR, IDN, IND, NZL, TUR, TWN, USA. ------ #### [ Sample request ] ``` { "QueryText": "101-910 Beach Avenue, Vancouver" } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "SecondaryAddress", "Title": "101-910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Address": { "Label": "101-910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Vancouver", "District": "Downtown Vancouver", "PostalCode": "V6Z 2W7", "Street": "Beach Ave", "StreetComponents": [ { "BaseName": "Beach", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "910", "SecondaryAddressComponents": [ { "Number": "101" } ] }, "Position": [ -123.1334, 49.27532 ], "MapView": [ -123.13478, 49.27442, -123.13202, 49.27622 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Locality": 1, "Intersection": [ 1 ], "AddressNumber": 1, "SecondaryAddressComponents": [ { "Number": 1 } ] } } }, "ParsedQuery": { "Address": { "Locality": [ { "StartIndex": 22, "EndIndex": 31, "Value": "Vancouver", "QueryComponent": "Query" } ], "Street": [ { "StartIndex": 8, "EndIndex": 20, "Value": "Beach Avenue", "QueryComponent": "Query" } ], "AddressNumber": [ { "StartIndex": 4, "EndIndex": 7, "Value": "910", "QueryComponent": "Query" } ], "SecondaryAddressComponents": [ { "StartIndex": 0, "EndIndex": 3, "Value": "101", "Number": "101", "Designator": "unknown" } ] } }, "MainAddress": { "PlaceId": "", "PlaceType": "PointAddress", "Title": "910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Address": { "Label": "910 Beach Ave, Vancouver, BC V6Z 2W7, Canada" }, "Position": [ -123.13325, 49.27542 ] } } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText":"101-910 Beach Avenue, Vancouver" }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "101-910 Beach Avenue, Vancouver" ``` ------ # How to get intersections `Intersections` allows you to retrieve all nearby intersections. This can potentially be used by emergency services and delivery couriers. ## Potential use cases + **Emergency response:** 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. + **Delivery couriers:** 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. ## Example ### Get secondary addresses ------ #### [ Sample request ] ``` { "QueryText":"910 Beach Avenue, Vancouver", "AdditionalFeatures": ["Intersections"] } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointAddress", "Title": "910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Address": { "Label": "910 Beach Ave, Vancouver, BC V6Z 2W7, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Vancouver", "District": "Downtown Vancouver", "PostalCode": "V6Z 2W7", "Street": "Beach Ave", "StreetComponents": [ { "BaseName": "Beach", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "910" }, "Position": [ -123.13325, 49.27542 ], "MapView": [ -123.13463, 49.27452, -123.13187, 49.27632 ], "MatchScores": { "Overall": 1, "Components": { "Address": { "Locality": 1, "Intersection": [ 1 ], "AddressNumber": 1 } } }, "ParsedQuery": { "Address": { "Locality": [ { "StartIndex": 18, "EndIndex": 27, "Value": "Vancouver", "QueryComponent": "Query" } ], "Street": [ { "StartIndex": 4, "EndIndex": 16, "Value": "Beach Avenue", "QueryComponent": "Query" } ], "AddressNumber": [ { "StartIndex": 0, "EndIndex": 3, "Value": "910", "QueryComponent": "Query" } ] } }, "Intersections": [ { "PlaceId": "", "Title": "Beach Ave & Hornby St, Vancouver, BC V6Z, Canada", "Address": { "Label": "Beach Ave & Hornby St, Vancouver, BC V6Z, Canada", "PostalCode": "V6Z", "Intersection": [ "Beach Ave", "Hornby St" ] }, "Position": [ -123.1328, 49.27536 ] }, { "PlaceId": "", "Title": "Beach Ave & Burrard St, Vancouver, BC, Canada", "Address": { "Label": "Beach Ave & Burrard St, Vancouver, BC, Canada", "Intersection": [ "Beach Ave", "Burrard St" ] }, "Position": [ -123.13377, 49.27599 ] } ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/geocode?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryText":"910 Beach Avenue, Vancouver", "AdditionalFeatures": ["Intersections"] }' ``` ------ #### [ AWS CLI ] ``` aws geo-places geocode --key ${YourKey} --query-text "910 Beach Avenue, Vancouver" --additional-features "Intersections" ``` ------