# Amazon Location Service Places V2 The following actions are supported by Amazon Location Service Places V2: + [Autocomplete](API_geoplaces_Autocomplete.md) + [Geocode](API_geoplaces_Geocode.md) + [GetPlace](API_geoplaces_GetPlace.md) + [ReverseGeocode](API_geoplaces_ReverseGeocode.md) + [SearchNearby](API_geoplaces_SearchNearby.md) + [SearchText](API_geoplaces_SearchText.md) + [Suggest](API_geoplaces_Suggest.md) # Autocomplete `Autocomplete` completes potential places and addresses as the user types, based on the partial input. The API enhances the efficiency and accuracy of address by completing query based on a few entered keystrokes. It helps you by completing partial queries with valid address completion. Also, the API supports the filtering of results based on geographic location, country, or specific place types, and can be tailored using optional parameters like language and political views. For more information, see [Autocomplete](https://docs.aws.amazon.com/location/latest/developerguide/autocomplete.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /autocomplete?key=Key HTTP/1.1 Content-type: application/json { "AdditionalFeatures": [ "string" ], "BiasPosition": [ number ], "Filter": { "BoundingBox": [ number ], "Circle": { "Center": [ number ], "Radius": number }, "IncludeCountries": [ "string" ], "IncludePlaceTypes": [ "string" ] }, "IntendedUse": "string", "Language": "string", "MaxResults": number, "PoliticalView": "string", "PostalCodeMode": "string", "QueryText": "string" } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_geoplaces_Autocomplete_RequestSyntax) ** Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. Length Constraints: Minimum length of 0. Maximum length of 1000. ## Request Body The request accepts the following data in JSON format. ** [AdditionalFeatures](#API_geoplaces_Autocomplete_RequestSyntax) ** A list of optional additional parameters that can be requested for each result. Type: Array of strings Array Members: Fixed number of 1 item. Valid Values: `Core` Required: No ** [BiasPosition](#API_geoplaces_Autocomplete_RequestSyntax) ** The position in longitude and latitude that the results should be close to. Typically, place results returned are ranked higher the closer they are to this position. Stored in `[lng, lat]` and in the WGS 84 format. The fields `BiasPosition`, `FilterBoundingBox`, and `FilterCircle` are mutually exclusive. Type: Array of doubles Array Members: Fixed number of 2 items. Required: No ** [Filter](#API_geoplaces_Autocomplete_RequestSyntax) ** A structure which contains a set of inclusion/exclusion properties that results must possess in order to be returned as a result. Type: [AutocompleteFilter](API_geoplaces_AutocompleteFilter.md) object Required: No ** [IntendedUse](#API_geoplaces_Autocomplete_RequestSyntax) ** Indicates if the query results will be persisted in customer infrastructure. Defaults to `SingleUse` (not stored). Currently, `Autocomplete` does not support storage of results. Type: String Valid Values: `SingleUse` Required: No ** [Language](#API_geoplaces_Autocomplete_RequestSyntax) ** A list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. Type: String Length Constraints: Minimum length of 2. Maximum length of 35. Required: No ** [MaxResults](#API_geoplaces_Autocomplete_RequestSyntax) ** An optional limit for the number of results returned in a single call. Default value: 5 Type: Integer Valid Range: Minimum value of 1. Maximum value of 20. Required: No ** [PoliticalView](#API_geoplaces_Autocomplete_RequestSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. The following political views are currently supported: + `ARG`: Argentina's view on the Southern Patagonian Ice Field and Tierra Del Fuego, including the Falkland Islands, South Georgia, and South Sandwich Islands + `EGY`: Egypt's view on Bir Tawil + `IND`: India's view on Gilgit-Baltistan + `KEN`: Kenya's view on the Ilemi Triangle + `MAR`: Morocco's view on Western Sahara + `RUS`: Russia's view on Crimea + `SDN`: Sudan's view on the Halaib Triangle + `SRB`: Serbia's view on Kosovo, Vukovar, and Sarengrad Islands + `SUR`: Suriname's view on the Courantyne Headwaters and Lawa Headwaters + `SYR`: Syria's view on the Golan Heights + `TUR`: Turkey's view on Cyprus and Northern Cyprus + `TZA`: Tanzania's view on Lake Malawi + `URY`: Uruguay's view on Rincon de Artigas + `VNM`: Vietnam's view on the Paracel Islands and Spratly Islands Type: String Length Constraints: Minimum length of 2. Maximum length of 3. Pattern: `([A-Z]{2}|[A-Z]{3})` Required: No ** [PostalCodeMode](#API_geoplaces_Autocomplete_RequestSyntax) ** The `PostalCodeMode` affects how postal code results are returned. If a postal code spans multiple localities and this value is empty, partial district or locality information may be returned under a single postal code result entry. If it's populated with the value `EnumerateSpannedLocalities`, all cities in that postal code are returned. Type: String Valid Values: `MergeAllSpannedLocalities | EnumerateSpannedLocalities` Required: No ** [QueryText](#API_geoplaces_Autocomplete_RequestSyntax) ** The free-form text query to match addresses against. This is usually a partially typed address from an end user in an address box or form. The fields `QueryText`, and `QueryID` are mutually exclusive. Type: String Length Constraints: Minimum length of 1. Maximum length of 200. Required: Yes ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "ResultItems": [ { "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "Distance": number, "Highlights": { "Address": { "AddressNumber": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Block": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Building": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Country": { "Code": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Name": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ] }, "District": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Intersection": [ [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ] ], "Label": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Locality": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "PostalCode": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Region": { "Code": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Name": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ] }, "Street": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "SubBlock": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "SubDistrict": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "SubRegion": { "Code": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ], "Name": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ] } }, "Title": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ] }, "Language": "string", "PlaceId": "string", "PlaceType": "string", "PoliticalView": "string", "Title": "string" } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_geoplaces_Autocomplete_ResponseSyntax) ** The pricing bucket for which the query is charged at. For more information on pricing, please visit [Amazon Location Service Pricing](https://aws.amazon.com/location/pricing/). The following data is returned in JSON format by the service. ** [ResultItems](#API_geoplaces_Autocomplete_ResponseSyntax) ** List of places or results returned for a query. Type: Array of [AutocompleteResultItem](API_geoplaces_AutocompleteResultItem.md) objects Array Members: Minimum number of 0 items. Maximum number of 20 items. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** AccessDeniedException ** You don't have sufficient access to perform this action. HTTP Status Code: 403 ** InternalServerException ** The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 ** ThrottlingException ** The request was denied due to request throttling. HTTP Status Code: 429 ** ValidationException ** The input fails to satisfy the constraints specified by an AWS service. ** FieldList ** Test stub for FieldList. ** Reason ** Test stub for reason HTTP Status Code: 400 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-places-2020-11-19/Autocomplete) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-places-2020-11-19/Autocomplete) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-places-2020-11-19/Autocomplete) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-places-2020-11-19/Autocomplete) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-places-2020-11-19/Autocomplete) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-places-2020-11-19/Autocomplete) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-places-2020-11-19/Autocomplete) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-places-2020-11-19/Autocomplete) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-places-2020-11-19/Autocomplete) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-places-2020-11-19/Autocomplete) # Geocode `Geocode` converts a textual address or place into geographic coordinates. You can obtain geographic coordinates, address component, and other related information. It supports flexible queries, including free-form text or structured queries with components like street names, postal codes, and regions. The Geocode API can also provide additional features such as time zone information and the inclusion of political views. For more information, see [Geocode](https://docs.aws.amazon.com/location/latest/developerguide/geocode.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /geocode?key=Key HTTP/1.1 Content-type: application/json { "AdditionalFeatures": [ "string" ], "BiasPosition": [ number ], "Filter": { "IncludeCountries": [ "string" ], "IncludePlaceTypes": [ "string" ] }, "IntendedUse": "string", "Language": "string", "MaxResults": number, "PoliticalView": "string", "QueryComponents": { "AddressNumber": "string", "Country": "string", "District": "string", "Locality": "string", "PostalCode": "string", "Region": "string", "Street": "string", "SubRegion": "string" }, "QueryText": "string" } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_geoplaces_Geocode_RequestSyntax) ** Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. Length Constraints: Minimum length of 0. Maximum length of 1000. ## Request Body The request accepts the following data in JSON format. ** [AdditionalFeatures](#API_geoplaces_Geocode_RequestSyntax) ** A list of optional additional parameters, such as time zone, that can be requested for each result. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 4 items. Valid Values: `TimeZone | Access | SecondaryAddresses | Intersections` Required: No ** [BiasPosition](#API_geoplaces_Geocode_RequestSyntax) ** The position, in longitude and latitude, that the results should be close to. Typically, place results returned are ranked higher the closer they are to this position. Stored in `[lng, lat]` and in the WGS 84 format. Type: Array of doubles Array Members: Fixed number of 2 items. Required: No ** [Filter](#API_geoplaces_Geocode_RequestSyntax) ** A structure which contains a set of inclusion/exclusion properties that results must possess in order to be returned as a result. Type: [GeocodeFilter](API_geoplaces_GeocodeFilter.md) object Required: No ** [IntendedUse](#API_geoplaces_Geocode_RequestSyntax) ** Indicates if the query results will be persisted in customer infrastructure. Defaults to `SingleUse` (not stored). Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. When storing `Geocode` responses, you *must* set this field to `Storage` to comply with the terms of service. These requests will be charged at a higher rate. Please review the [user agreement](https://aws.amazon.com/location/sla/) and [service pricing structure](https://aws.amazon.com/location/pricing/) to determine the correct setting for your use case. Type: String Valid Values: `SingleUse | Storage` Required: No ** [Language](#API_geoplaces_Geocode_RequestSyntax) ** A list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. Type: String Length Constraints: Minimum length of 2. Maximum length of 35. Required: No ** [MaxResults](#API_geoplaces_Geocode_RequestSyntax) ** An optional limit for the number of results returned in a single call. Default value: 20 Type: Integer Valid Range: Minimum value of 1. Maximum value of 100. Required: No ** [PoliticalView](#API_geoplaces_Geocode_RequestSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. Type: String Length Constraints: Minimum length of 2. Maximum length of 3. Pattern: `([A-Z]{2}|[A-Z]{3})` Required: No ** [QueryComponents](#API_geoplaces_Geocode_RequestSyntax) ** A structured free text query allows you to search for places by the name or text representation of specific properties of the place. Type: [GeocodeQueryComponents](API_geoplaces_GeocodeQueryComponents.md) object Required: No ** [QueryText](#API_geoplaces_Geocode_RequestSyntax) ** The free-form text query to match addresses against. This is usually a partially typed address from an end user in an address box or form. Type: String Length Constraints: Minimum length of 1. Maximum length of 200. Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "ResultItems": [ { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "AddressNumberCorrected": boolean, "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Distance": number, "FoodTypes": [ { "Id": "string", "LocalizedName": "string", "Primary": boolean } ], "Intersections": [ { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "Distance": number, "MapView": [ number ], "PlaceId": "string", "Position": [ number ], "RouteDistance": number, "Title": "string" } ], "MainAddress": { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "PlaceId": "string", "PlaceType": "string", "Position": [ number ], "Title": "string" }, "MapView": [ number ], "MatchScores": { "Components": { "Address": { "AddressNumber": number, "Block": number, "Building": number, "Country": number, "District": number, "Intersection": [ number ], "Locality": number, "PostalCode": number, "Region": number, "SecondaryAddressComponents": [ { "Number": number } ], "SubBlock": number, "SubDistrict": number, "SubRegion": number }, "Title": number }, "Overall": number }, "ParsedQuery": { "Address": { "AddressNumber": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "Block": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "Building": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "Country": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "District": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "Locality": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "PostalCode": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "Region": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "SecondaryAddressComponents": [ { "Designator": "string", "EndIndex": number, "Number": "string", "StartIndex": number, "Value": "string" } ], "Street": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "SubBlock": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "SubDistrict": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ], "SubRegion": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ] }, "Title": [ { "EndIndex": number, "QueryComponent": "string", "StartIndex": number, "Value": "string" } ] }, "PlaceId": "string", "PlaceType": "string", "PoliticalView": "string", "Position": [ number ], "PostalCodeDetails": [ { "PostalAuthority": "string", "PostalCode": "string", "PostalCodeType": "string", "UspsZip": { "ZipClassificationCode": "string" }, "UspsZipPlus4": { "RecordTypeCode": "string" } } ], "SecondaryAddresses": [ { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "PlaceId": "string", "PlaceType": "string", "Position": [ number ], "Title": "string" } ], "TimeZone": { "Name": "string", "Offset": "string", "OffsetSeconds": number }, "Title": "string" } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_geoplaces_Geocode_ResponseSyntax) ** The pricing bucket for which the query is charged at, or the maximum pricing bucket when the query is charged per item within the query. For more information on pricing, please visit [Amazon Location Service Pricing](https://aws.amazon.com/location/pricing/). The following data is returned in JSON format by the service. ** [ResultItems](#API_geoplaces_Geocode_ResponseSyntax) ** List of places or results returned for a query. Type: Array of [GeocodeResultItem](API_geoplaces_GeocodeResultItem.md) objects Array Members: Minimum number of 0 items. Maximum number of 100 items. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** AccessDeniedException ** You don't have sufficient access to perform this action. HTTP Status Code: 403 ** InternalServerException ** The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 ** ThrottlingException ** The request was denied due to request throttling. HTTP Status Code: 429 ** ValidationException ** The input fails to satisfy the constraints specified by an AWS service. ** FieldList ** Test stub for FieldList. ** Reason ** Test stub for reason HTTP Status Code: 400 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-places-2020-11-19/Geocode) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-places-2020-11-19/Geocode) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-places-2020-11-19/Geocode) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-places-2020-11-19/Geocode) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-places-2020-11-19/Geocode) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-places-2020-11-19/Geocode) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-places-2020-11-19/Geocode) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-places-2020-11-19/Geocode) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-places-2020-11-19/Geocode) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-places-2020-11-19/Geocode) # GetPlace `GetPlace` finds a place by its unique ID. A `PlaceId` is returned by other place operations. For more information, see [GetPlace](https://docs.aws.amazon.com/location/latest/developerguide/get-place.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` GET /place/PlaceId?additional-features=AdditionalFeatures&intended-use=IntendedUse&key=Key&language=Language&political-view=PoliticalView HTTP/1.1 ``` ## URI Request Parameters The request uses the following URI parameters. ** [AdditionalFeatures](#API_geoplaces_GetPlace_RequestSyntax) ** A list of optional additional parameters such as time zone that can be requested for each result. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the `TimeZone` value. Array Members: Minimum number of 1 item. Maximum number of 5 items. Valid Values: `TimeZone | Phonemes | Access | Contact | SecondaryAddresses` ** [IntendedUse](#API_geoplaces_GetPlace_RequestSyntax) ** Indicates if the query results will be persisted in customer infrastructure. Defaults to `SingleUse` (not stored). Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. When storing `GetPlace` responses, you *must* set this field to `Storage` to comply with the terms of service. These requests will be charged at a higher rate. Please review the [user agreement](https://aws.amazon.com/location/sla/) and [service pricing structure](https://aws.amazon.com/location/pricing/) to determine the correct setting for your use case. Valid Values: `SingleUse | Storage` ** [Key](#API_geoplaces_GetPlace_RequestSyntax) ** Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. Length Constraints: Minimum length of 0. Maximum length of 1000. ** [Language](#API_geoplaces_GetPlace_RequestSyntax) ** A list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the following codes: `en, id, km, lo, ms, my, pt, th, tl, vi, zh` Length Constraints: Minimum length of 2. Maximum length of 35. ** [PlaceId](#API_geoplaces_GetPlace_RequestSyntax) ** The `PlaceId` of the place you wish to receive the information for. Length Constraints: Minimum length of 0. Maximum length of 500. Required: Yes ** [PoliticalView](#API_geoplaces_GetPlace_RequestSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Length Constraints: Minimum length of 2. Maximum length of 3. Pattern: `([A-Z]{2}|[A-Z]{3})` ## Request Body The request does not have a request body. ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "AccessPoints": [ { "Position": [ number ] } ], "AccessRestrictions": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Restricted": boolean } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "AddressNumberCorrected": boolean, "BusinessChains": [ { "Id": "string", "Name": "string" } ], "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Contacts": { "Emails": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Faxes": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Phones": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Websites": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ] }, "FoodTypes": [ { "Id": "string", "LocalizedName": "string", "Primary": boolean } ], "MainAddress": { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "PlaceId": "string", "PlaceType": "string", "Position": [ number ], "Title": "string" }, "MapView": [ number ], "OpeningHours": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Components": [ { "OpenDuration": "string", "OpenTime": "string", "Recurrence": "string" } ], "Display": [ "string" ], "OpenNow": boolean } ], "Phonemes": { "Address": { "Block": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Country": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "District": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Locality": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Region": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Street": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubBlock": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubDistrict": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubRegion": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "Title": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "PlaceId": "string", "PlaceType": "string", "PoliticalView": "string", "Position": [ number ], "PostalCodeDetails": [ { "PostalAuthority": "string", "PostalCode": "string", "PostalCodeType": "string", "UspsZip": { "ZipClassificationCode": "string" }, "UspsZipPlus4": { "RecordTypeCode": "string" } } ], "SecondaryAddresses": [ { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "PlaceId": "string", "PlaceType": "string", "Position": [ number ], "Title": "string" } ], "TimeZone": { "Name": "string", "Offset": "string", "OffsetSeconds": number }, "Title": "string" } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_geoplaces_GetPlace_ResponseSyntax) ** The pricing bucket for which the query is charged at. For more information on pricing, please visit [Amazon Location Service Pricing](https://aws.amazon.com/location/pricing/). The following data is returned in JSON format by the service. ** [AccessPoints](#API_geoplaces_GetPlace_ResponseSyntax) ** Position of the access point in World Geodetic System (WGS 84) format: [longitude, latitude]. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of [AccessPoint](API_geoplaces_AccessPoint.md) objects Array Members: Minimum number of 0 items. Maximum number of 100 items. ** [AccessRestrictions](#API_geoplaces_GetPlace_ResponseSyntax) ** Indicates known access restrictions on a vehicle access point. The index correlates to an access point and indicates if access through this point has some form of restriction. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of [AccessRestriction](API_geoplaces_AccessRestriction.md) objects Array Members: Minimum number of 1 item. Maximum number of 100 items. ** [Address](#API_geoplaces_GetPlace_ResponseSyntax) ** The place's address. Type: [Address](API_geoplaces_Address.md) object ** [AddressNumberCorrected](#API_geoplaces_GetPlace_ResponseSyntax) ** Boolean indicating if the address provided has been corrected. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Boolean ** [BusinessChains](#API_geoplaces_GetPlace_ResponseSyntax) ** The Business Chains associated with the place. Type: Array of [BusinessChain](API_geoplaces_BusinessChain.md) objects Array Members: Minimum number of 1 item. Maximum number of 100 items. ** [Categories](#API_geoplaces_GetPlace_ResponseSyntax) ** Categories of results that results must belong to. Type: Array of [Category](API_geoplaces_Category.md) objects Array Members: Minimum number of 1 item. Maximum number of 100 items. ** [Contacts](#API_geoplaces_GetPlace_ResponseSyntax) ** List of potential contact methods for the result/place. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [Contacts](API_geoplaces_Contacts.md) object ** [FoodTypes](#API_geoplaces_GetPlace_ResponseSyntax) ** List of food types offered by this result. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of [FoodType](API_geoplaces_FoodType.md) objects Array Members: Minimum number of 1 item. Maximum number of 100 items. ** [MainAddress](#API_geoplaces_GetPlace_ResponseSyntax) ** The main address corresponding to a place of type Secondary Address. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RelatedPlace](API_geoplaces_RelatedPlace.md) object ** [MapView](#API_geoplaces_GetPlace_ResponseSyntax) ** The bounding box enclosing the geometric shape (area or line) that an individual result covers. The bounding box formed is defined as a set of four coordinates: `[{westward lng}, {southern lat}, {eastward lng}, {northern lat}]` Type: Array of doubles Array Members: Fixed number of 4 items. ** [OpeningHours](#API_geoplaces_GetPlace_ResponseSyntax) ** List of opening hours objects. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of [OpeningHours](API_geoplaces_OpeningHours.md) objects Array Members: Minimum number of 1 item. Maximum number of 100 items. ** [Phonemes](#API_geoplaces_GetPlace_ResponseSyntax) ** How the various components of the result's address are pronounced in various languages. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [PhonemeDetails](API_geoplaces_PhonemeDetails.md) object ** [PlaceId](#API_geoplaces_GetPlace_ResponseSyntax) ** The `PlaceId` of the place you wish to receive the information for. Type: String Length Constraints: Minimum length of 0. Maximum length of 500. ** [PlaceType](#API_geoplaces_GetPlace_ResponseSyntax) ** A `PlaceType` is a category that the result place must belong to. Type: String Valid Values: `Country | Region | SubRegion | Locality | District | SubDistrict | PostalCode | Block | SubBlock | Intersection | Street | PointOfInterest | PointAddress | InterpolatedAddress | SecondaryAddress | InferredSecondaryAddress` ** [PoliticalView](#API_geoplaces_GetPlace_ResponseSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: String Length Constraints: Fixed length of 3. Pattern: `[A-Z]{3}` ** [Position](#API_geoplaces_GetPlace_ResponseSyntax) ** The position in World Geodetic System (WGS 84) format: [longitude, latitude]. Type: Array of doubles Array Members: Fixed number of 2 items. ** [PostalCodeDetails](#API_geoplaces_GetPlace_ResponseSyntax) ** Contains details about the postal code of the place/result. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of [PostalCodeDetails](API_geoplaces_PostalCodeDetails.md) objects Array Members: Minimum number of 0 items. Maximum number of 100 items. ** [SecondaryAddresses](#API_geoplaces_GetPlace_ResponseSyntax) ** All secondary addresses that are associated with a main address. A secondary address is one that includes secondary designators, such as a Suite or Unit Number, Building, or Floor information. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Coverage for this functionality is available in the following countries: AUS, CAN, NZL, USA, PRI. Type: Array of [RelatedPlace](API_geoplaces_RelatedPlace.md) objects Array Members: Minimum number of 1 item. ** [TimeZone](#API_geoplaces_GetPlace_ResponseSyntax) ** The time zone in which the place is located. Type: [TimeZone](API_geoplaces_TimeZone.md) object ** [Title](#API_geoplaces_GetPlace_ResponseSyntax) ** The localized display name of this result item based on request parameter `language`. Type: String Length Constraints: Minimum length of 0. Maximum length of 200. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** AccessDeniedException ** You don't have sufficient access to perform this action. HTTP Status Code: 403 ** InternalServerException ** The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 ** ThrottlingException ** The request was denied due to request throttling. HTTP Status Code: 429 ** ValidationException ** The input fails to satisfy the constraints specified by an AWS service. ** FieldList ** Test stub for FieldList. ** Reason ** Test stub for reason HTTP Status Code: 400 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-places-2020-11-19/GetPlace) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-places-2020-11-19/GetPlace) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-places-2020-11-19/GetPlace) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-places-2020-11-19/GetPlace) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-places-2020-11-19/GetPlace) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-places-2020-11-19/GetPlace) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-places-2020-11-19/GetPlace) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-places-2020-11-19/GetPlace) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-places-2020-11-19/GetPlace) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-places-2020-11-19/GetPlace) # ReverseGeocode `ReverseGeocode` converts geographic coordinates into a human-readable address or place. You can obtain address component, and other related information such as place type, category, street information. The Reverse Geocode API supports filtering to on place type so that you can refine result based on your need. Also, The Reverse Geocode API can also provide additional features such as time zone information and the inclusion of political views. For more information, see [Reverse Geocode](https://docs.aws.amazon.com/location/latest/developerguide/reverse-geocode.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /reverse-geocode?key=Key HTTP/1.1 Content-type: application/json { "AdditionalFeatures": [ "string" ], "Filter": { "IncludePlaceTypes": [ "string" ] }, "Heading": number, "IntendedUse": "string", "Language": "string", "MaxResults": number, "PoliticalView": "string", "QueryPosition": [ number ], "QueryRadius": number } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_geoplaces_ReverseGeocode_RequestSyntax) ** Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. Length Constraints: Minimum length of 0. Maximum length of 1000. ## Request Body The request accepts the following data in JSON format. ** [AdditionalFeatures](#API_geoplaces_ReverseGeocode_RequestSyntax) ** A list of optional additional parameters, such as time zone that can be requested for each result. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the `TimeZone` value. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 3 items. Valid Values: `TimeZone | Access | Intersections` Required: No ** [Filter](#API_geoplaces_ReverseGeocode_RequestSyntax) ** A structure which contains a set of inclusion/exclusion properties that results must possess in order to be returned as a result. Type: [ReverseGeocodeFilter](API_geoplaces_ReverseGeocodeFilter.md) object Required: No ** [Heading](#API_geoplaces_ReverseGeocode_RequestSyntax) ** The heading in degrees from true north in a navigation context. The heading is measured as the angle clockwise from the North direction. Example: North is `0` degrees, East is `90` degrees, South is `180` degrees, and West is `270` degrees. Type: Double Valid Range: Minimum value of 0.0. Maximum value of 360.0. Required: No ** [IntendedUse](#API_geoplaces_ReverseGeocode_RequestSyntax) ** Indicates if the query results will be persisted in customer infrastructure. Defaults to `SingleUse` (not stored). When storing `ReverseGeocode` responses, you *must* set this field to `Storage` to comply with the terms of service. These requests will be charged at a higher rate. Please review the [user agreement](https://aws.amazon.com/location/sla/) and [service pricing structure](https://aws.amazon.com/location/pricing/) to determine the correct setting for your use case. Type: String Valid Values: `SingleUse | Storage` Required: No ** [Language](#API_geoplaces_ReverseGeocode_RequestSyntax) ** A list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the following codes: `en, id, km, lo, ms, my, pt, th, tl, vi, zh` Type: String Length Constraints: Minimum length of 2. Maximum length of 35. Required: No ** [MaxResults](#API_geoplaces_ReverseGeocode_RequestSyntax) ** An optional limit for the number of results returned in a single call. Default value: 1 Type: Integer Valid Range: Minimum value of 1. Maximum value of 100. Required: No ** [PoliticalView](#API_geoplaces_ReverseGeocode_RequestSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: String Length Constraints: Minimum length of 2. Maximum length of 3. Pattern: `([A-Z]{2}|[A-Z]{3})` Required: No ** [QueryPosition](#API_geoplaces_ReverseGeocode_RequestSyntax) ** The position in World Geodetic System (WGS 84) format: [longitude, latitude] for which you are querying nearby results for. Results closer to the position will be ranked higher then results further away from the position Type: Array of doubles Array Members: Fixed number of 2 items. Required: Yes ** [QueryRadius](#API_geoplaces_ReverseGeocode_RequestSyntax) ** The maximum distance in meters from the QueryPosition from which a result will be returned. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only up to a maximum value of 100,000. Type: Long Valid Range: Minimum value of 1. Maximum value of 21000000. Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "ResultItems": [ { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "AddressNumberCorrected": boolean, "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Distance": number, "FoodTypes": [ { "Id": "string", "LocalizedName": "string", "Primary": boolean } ], "Intersections": [ { "AccessPoints": [ { "Position": [ number ] } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "Distance": number, "MapView": [ number ], "PlaceId": "string", "Position": [ number ], "RouteDistance": number, "Title": "string" } ], "MapView": [ number ], "PlaceId": "string", "PlaceType": "string", "PoliticalView": "string", "Position": [ number ], "PostalCodeDetails": [ { "PostalAuthority": "string", "PostalCode": "string", "PostalCodeType": "string", "UspsZip": { "ZipClassificationCode": "string" }, "UspsZipPlus4": { "RecordTypeCode": "string" } } ], "TimeZone": { "Name": "string", "Offset": "string", "OffsetSeconds": number }, "Title": "string" } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_geoplaces_ReverseGeocode_ResponseSyntax) ** The pricing bucket for which the query is charged at. For more information on pricing, please visit [Amazon Location Service Pricing](https://aws.amazon.com/location/pricing/). The following data is returned in JSON format by the service. ** [ResultItems](#API_geoplaces_ReverseGeocode_ResponseSyntax) ** List of places or results returned for a query. Type: Array of [ReverseGeocodeResultItem](API_geoplaces_ReverseGeocodeResultItem.md) objects Array Members: Minimum number of 0 items. Maximum number of 100 items. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** AccessDeniedException ** You don't have sufficient access to perform this action. HTTP Status Code: 403 ** InternalServerException ** The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 ** ThrottlingException ** The request was denied due to request throttling. HTTP Status Code: 429 ** ValidationException ** The input fails to satisfy the constraints specified by an AWS service. ** FieldList ** Test stub for FieldList. ** Reason ** Test stub for reason HTTP Status Code: 400 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-places-2020-11-19/ReverseGeocode) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-places-2020-11-19/ReverseGeocode) # SearchNearby `SearchNearby` queries for points of interest within a radius from a central coordinates, returning place results with optional filters such as categories, business chains, food types and more. The API returns details such as a place name, address, phone, category, food type, contact, opening hours. Also, the API can return phonemes, time zones and more based on requested parameters. For more information, see [Search Nearby](https://docs.aws.amazon.com/location/latest/developerguide/search-nearby.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /search-nearby?key=Key HTTP/1.1 Content-type: application/json { "AdditionalFeatures": [ "string" ], "Filter": { "BoundingBox": [ number ], "ExcludeBusinessChains": [ "string" ], "ExcludeCategories": [ "string" ], "ExcludeFoodTypes": [ "string" ], "IncludeBusinessChains": [ "string" ], "IncludeCategories": [ "string" ], "IncludeCountries": [ "string" ], "IncludeFoodTypes": [ "string" ] }, "IntendedUse": "string", "Language": "string", "MaxResults": number, "NextToken": "string", "PoliticalView": "string", "QueryPosition": [ number ], "QueryRadius": number } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_geoplaces_SearchNearby_RequestSyntax) ** Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. Length Constraints: Minimum length of 0. Maximum length of 1000. ## Request Body The request accepts the following data in JSON format. ** [AdditionalFeatures](#API_geoplaces_SearchNearby_RequestSyntax) ** A list of optional additional parameters, such as time zone, that can be requested for each result. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 4 items. Valid Values: `TimeZone | Phonemes | Access | Contact` Required: No ** [Filter](#API_geoplaces_SearchNearby_RequestSyntax) ** A structure which contains a set of inclusion/exclusion properties that results must possess in order to be returned as a result. Type: [SearchNearbyFilter](API_geoplaces_SearchNearbyFilter.md) object Required: No ** [IntendedUse](#API_geoplaces_SearchNearby_RequestSyntax) ** Indicates if the query results will be persisted in customer infrastructure. Defaults to `SingleUse` (not stored). Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. When storing `SearchNearby` responses, you *must* set this field to `Storage` to comply with the terms of service. These requests will be charged at a higher rate. Please review the [user agreement](https://aws.amazon.com/location/sla/) and [service pricing structure](https://aws.amazon.com/location/pricing/) to determine the correct setting for your use case. Type: String Valid Values: `SingleUse | Storage` Required: No ** [Language](#API_geoplaces_SearchNearby_RequestSyntax) ** A list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. Type: String Length Constraints: Minimum length of 2. Maximum length of 35. Required: No ** [MaxResults](#API_geoplaces_SearchNearby_RequestSyntax) ** An optional limit for the number of results returned in a single call. Default value: 20 Type: Integer Valid Range: Minimum value of 1. Maximum value of 100. Required: No ** [NextToken](#API_geoplaces_SearchNearby_RequestSyntax) ** If `nextToken` is returned, there are more results available. The value of `nextToken` is a unique pagination token for each page. Type: String Length Constraints: Minimum length of 1. Maximum length of 2000. Required: No ** [PoliticalView](#API_geoplaces_SearchNearby_RequestSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. Type: String Length Constraints: Minimum length of 2. Maximum length of 3. Pattern: `([A-Z]{2}|[A-Z]{3})` Required: No ** [QueryPosition](#API_geoplaces_SearchNearby_RequestSyntax) ** The position in World Geodetic System (WGS 84) format: [longitude, latitude] for which you are querying nearby results for. Results closer to the position will be ranked higher then results further away from the position Type: Array of doubles Array Members: Fixed number of 2 items. Required: Yes ** [QueryRadius](#API_geoplaces_SearchNearby_RequestSyntax) ** The maximum distance in meters from the QueryPosition from which a result will be returned. The fields `QueryText`, and `QueryID` are mutually exclusive. Type: Long Valid Range: Minimum value of 1. Maximum value of 21000000. Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "NextToken": "string", "ResultItems": [ { "AccessPoints": [ { "Position": [ number ] } ], "AccessRestrictions": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Restricted": boolean } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "AddressNumberCorrected": boolean, "BusinessChains": [ { "Id": "string", "Name": "string" } ], "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Contacts": { "Emails": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Faxes": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Phones": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Websites": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ] }, "Distance": number, "FoodTypes": [ { "Id": "string", "LocalizedName": "string", "Primary": boolean } ], "MapView": [ number ], "OpeningHours": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Components": [ { "OpenDuration": "string", "OpenTime": "string", "Recurrence": "string" } ], "Display": [ "string" ], "OpenNow": boolean } ], "Phonemes": { "Address": { "Block": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Country": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "District": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Locality": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Region": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Street": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubBlock": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubDistrict": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubRegion": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "Title": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "PlaceId": "string", "PlaceType": "string", "PoliticalView": "string", "Position": [ number ], "TimeZone": { "Name": "string", "Offset": "string", "OffsetSeconds": number }, "Title": "string" } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_geoplaces_SearchNearby_ResponseSyntax) ** The pricing bucket for which the query is charged at. For more information on pricing, please visit [Amazon Location Service Pricing](https://aws.amazon.com/location/pricing/). The following data is returned in JSON format by the service. ** [NextToken](#API_geoplaces_SearchNearby_ResponseSyntax) ** If `nextToken` is returned, there are more results available. The value of `nextToken` is a unique pagination token for each page. Type: String Length Constraints: Minimum length of 1. Maximum length of 2000. ** [ResultItems](#API_geoplaces_SearchNearby_ResponseSyntax) ** List of places or results returned for a query. Type: Array of [SearchNearbyResultItem](API_geoplaces_SearchNearbyResultItem.md) objects Array Members: Minimum number of 0 items. Maximum number of 100 items. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** AccessDeniedException ** You don't have sufficient access to perform this action. HTTP Status Code: 403 ** InternalServerException ** The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 ** ThrottlingException ** The request was denied due to request throttling. HTTP Status Code: 429 ** ValidationException ** The input fails to satisfy the constraints specified by an AWS service. ** FieldList ** Test stub for FieldList. ** Reason ** Test stub for reason HTTP Status Code: 400 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-places-2020-11-19/SearchNearby) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-places-2020-11-19/SearchNearby) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-places-2020-11-19/SearchNearby) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-places-2020-11-19/SearchNearby) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-places-2020-11-19/SearchNearby) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-places-2020-11-19/SearchNearby) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-places-2020-11-19/SearchNearby) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-places-2020-11-19/SearchNearby) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-places-2020-11-19/SearchNearby) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-places-2020-11-19/SearchNearby) # SearchText `SearchText` searches for geocode and place information. You can then complete a follow-up query suggested from the `Suggest` API via a query id. For more information, see [Search Text](https://docs.aws.amazon.com/location/latest/developerguide/search-text.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /search-text?key=Key HTTP/1.1 Content-type: application/json { "AdditionalFeatures": [ "string" ], "BiasPosition": [ number ], "Filter": { "BoundingBox": [ number ], "Circle": { "Center": [ number ], "Radius": number }, "IncludeCountries": [ "string" ] }, "IntendedUse": "string", "Language": "string", "MaxResults": number, "NextToken": "string", "PoliticalView": "string", "QueryId": "string", "QueryText": "string" } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_geoplaces_SearchText_RequestSyntax) ** Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. Length Constraints: Minimum length of 0. Maximum length of 1000. ## Request Body The request accepts the following data in JSON format. ** [AdditionalFeatures](#API_geoplaces_SearchText_RequestSyntax) ** A list of optional additional parameters, such as time zone, that can be requested for each result. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the `TimeZone` value. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 4 items. Valid Values: `TimeZone | Phonemes | Access | Contact` Required: No ** [BiasPosition](#API_geoplaces_SearchText_RequestSyntax) ** The position, in longitude and latitude, that the results should be close to. Typically, place results returned are ranked higher the closer they are to this position. Stored in `[lng, lat]` and in the WGS 84 format. Exactly one of the following fields must be set: `BiasPosition`, `Filter.BoundingBox`, or `Filter.Circle`. Type: Array of doubles Array Members: Fixed number of 2 items. Required: No ** [Filter](#API_geoplaces_SearchText_RequestSyntax) ** A structure which contains a set of inclusion/exclusion properties that results must possess in order to be returned as a result. Type: [SearchTextFilter](API_geoplaces_SearchTextFilter.md) object Required: No ** [IntendedUse](#API_geoplaces_SearchText_RequestSyntax) ** Indicates if the query results will be persisted in customer infrastructure. Defaults to `SingleUse` (not stored). When storing `SearchText` responses, you *must* set this field to `Storage` to comply with the terms of service. These requests will be charged at a higher rate. Please review the [user agreement](https://aws.amazon.com/location/sla/) and [service pricing structure](https://aws.amazon.com/location/pricing/) to determine the correct setting for your use case. Type: String Valid Values: `SingleUse | Storage` Required: No ** [Language](#API_geoplaces_SearchText_RequestSyntax) ** A list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the following codes: `en, id, km, lo, ms, my, pt, th, tl, vi, zh` Type: String Length Constraints: Minimum length of 2. Maximum length of 35. Required: No ** [MaxResults](#API_geoplaces_SearchText_RequestSyntax) ** An optional limit for the number of results returned in a single call. Default value: 20 Type: Integer Valid Range: Minimum value of 1. Maximum value of 100. Required: No ** [NextToken](#API_geoplaces_SearchText_RequestSyntax) ** If `nextToken` is returned, there are more results available. The value of `nextToken` is a unique pagination token for each page. Type: String Length Constraints: Minimum length of 1. Maximum length of 2000. Required: No ** [PoliticalView](#API_geoplaces_SearchText_RequestSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: String Length Constraints: Minimum length of 2. Maximum length of 3. Pattern: `([A-Z]{2}|[A-Z]{3})` Required: No ** [QueryId](#API_geoplaces_SearchText_RequestSyntax) ** The query Id returned by the suggest API. If passed in the request, the SearchText API will preform a SearchText query with the improved query terms for the original query made to the suggest API. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Exactly one of the following fields must be set: `QueryText` or `QueryId`. Type: String Length Constraints: Minimum length of 1. Maximum length of 500. Required: No ** [QueryText](#API_geoplaces_SearchText_RequestSyntax) ** The free-form text query to match addresses against. This is usually a partially typed address from an end user in an address box or form. Exactly one of the following fields must be set: `QueryText` or `QueryId`. Type: String Length Constraints: Minimum length of 1. Maximum length of 200. Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "NextToken": "string", "ResultItems": [ { "AccessPoints": [ { "Position": [ number ] } ], "AccessRestrictions": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Restricted": boolean } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "AddressNumberCorrected": boolean, "BusinessChains": [ { "Id": "string", "Name": "string" } ], "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Contacts": { "Emails": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Faxes": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Phones": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ], "Websites": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Label": "string", "Value": "string" } ] }, "Distance": number, "FoodTypes": [ { "Id": "string", "LocalizedName": "string", "Primary": boolean } ], "MapView": [ number ], "OpeningHours": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Components": [ { "OpenDuration": "string", "OpenTime": "string", "Recurrence": "string" } ], "Display": [ "string" ], "OpenNow": boolean } ], "Phonemes": { "Address": { "Block": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Country": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "District": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Locality": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Region": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Street": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubBlock": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubDistrict": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubRegion": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "Title": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "PlaceId": "string", "PlaceType": "string", "PoliticalView": "string", "Position": [ number ], "TimeZone": { "Name": "string", "Offset": "string", "OffsetSeconds": number }, "Title": "string" } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_geoplaces_SearchText_ResponseSyntax) ** The pricing bucket for which the query is charged at. For more information on pricing, please visit [Amazon Location Service Pricing](https://aws.amazon.com/location/pricing/). The following data is returned in JSON format by the service. ** [NextToken](#API_geoplaces_SearchText_ResponseSyntax) ** If `nextToken` is returned, there are more results available. The value of `nextToken` is a unique pagination token for each page. Type: String Length Constraints: Minimum length of 1. Maximum length of 2000. ** [ResultItems](#API_geoplaces_SearchText_ResponseSyntax) ** List of places or results returned for a query. Type: Array of [SearchTextResultItem](API_geoplaces_SearchTextResultItem.md) objects Array Members: Minimum number of 0 items. Maximum number of 100 items. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** AccessDeniedException ** You don't have sufficient access to perform this action. HTTP Status Code: 403 ** InternalServerException ** The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 ** ThrottlingException ** The request was denied due to request throttling. HTTP Status Code: 429 ** ValidationException ** The input fails to satisfy the constraints specified by an AWS service. ** FieldList ** Test stub for FieldList. ** Reason ** Test stub for reason HTTP Status Code: 400 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-places-2020-11-19/SearchText) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-places-2020-11-19/SearchText) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-places-2020-11-19/SearchText) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-places-2020-11-19/SearchText) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-places-2020-11-19/SearchText) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-places-2020-11-19/SearchText) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-places-2020-11-19/SearchText) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-places-2020-11-19/SearchText) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-places-2020-11-19/SearchText) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-places-2020-11-19/SearchText) # Suggest `Suggest` provides intelligent predictions or recommendations based on the user's input or context, such as relevant places, points of interest, query terms or search category. It is designed to help users find places or point of interests candidates or identify a follow on query based on incomplete or misspelled queries. It returns a list of possible matches or refinements that can be used to formulate a more accurate query. Users can select the most appropriate suggestion and use it for further searching. The API provides options for filtering results by location and other attributes, and allows for additional features like phonemes and timezones. The response includes refined query terms and detailed place information. For more information, see [Suggest](https://docs.aws.amazon.com/location/latest/developerguide/suggest.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /suggest?key=Key HTTP/1.1 Content-type: application/json { "AdditionalFeatures": [ "string" ], "BiasPosition": [ number ], "Filter": { "BoundingBox": [ number ], "Circle": { "Center": [ number ], "Radius": number }, "IncludeCountries": [ "string" ] }, "IntendedUse": "string", "Language": "string", "MaxQueryRefinements": number, "MaxResults": number, "PoliticalView": "string", "QueryText": "string" } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_geoplaces_Suggest_RequestSyntax) ** Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. Length Constraints: Minimum length of 0. Maximum length of 1000. ## Request Body The request accepts the following data in JSON format. ** [AdditionalFeatures](#API_geoplaces_Suggest_RequestSyntax) ** A list of optional additional parameters, such as time zone, that can be requested for each result. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the `Core` and `TimeZone` values. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 4 items. Valid Values: `Core | TimeZone | Phonemes | Access` Required: No ** [BiasPosition](#API_geoplaces_Suggest_RequestSyntax) ** The position, in longitude and latitude, that the results should be close to. Typically, place results returned are ranked higher the closer they are to this position. Stored in `[lng, lat]` and in the WGS 84 format. The fields `BiasPosition`, `FilterBoundingBox`, and `FilterCircle` are mutually exclusive. Type: Array of doubles Array Members: Fixed number of 2 items. Required: No ** [Filter](#API_geoplaces_Suggest_RequestSyntax) ** A structure which contains a set of inclusion/exclusion properties that results must possess in order to be returned as a result. Type: [SuggestFilter](API_geoplaces_SuggestFilter.md) object Required: No ** [IntendedUse](#API_geoplaces_Suggest_RequestSyntax) ** Indicates if the query results will be persisted in customer infrastructure. Defaults to `SingleUse` (not stored). Currently, `Suggest` does not support storage of results. Type: String Valid Values: `SingleUse` Required: No ** [Language](#API_geoplaces_Suggest_RequestSyntax) ** A list of [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) compliant language codes for the results to be rendered in. If there is no data for the result in the requested language, data will be returned in the default language for the entry. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only the following codes: `en, id, km, lo, ms, my, pt, th, tl, vi, zh` Type: String Length Constraints: Minimum length of 2. Maximum length of 35. Required: No ** [MaxQueryRefinements](#API_geoplaces_Suggest_RequestSyntax) ** Maximum number of query terms to be returned for use with a search text query. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Integer Valid Range: Minimum value of 1. Maximum value of 10. Required: No ** [MaxResults](#API_geoplaces_Suggest_RequestSyntax) ** An optional limit for the number of results returned in a single call. Default value: 20 Type: Integer Valid Range: Minimum value of 1. Maximum value of 100. Required: No ** [PoliticalView](#API_geoplaces_Suggest_RequestSyntax) ** The alpha-2 or alpha-3 character code for the political view of a country. The political view applies to the results of the request to represent unresolved territorial claims through the point of view of the specified country. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: String Length Constraints: Minimum length of 2. Maximum length of 3. Pattern: `([A-Z]{2}|[A-Z]{3})` Required: No ** [QueryText](#API_geoplaces_Suggest_RequestSyntax) ** The free-form text query to match addresses against. This is usually a partially typed address from an end user in an address box or form. The fields `QueryText` and `QueryID` are mutually exclusive. Type: String Length Constraints: Minimum length of 1. Maximum length of 200. Required: Yes ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "QueryRefinements": [ { "EndIndex": number, "OriginalTerm": "string", "RefinedTerm": "string", "StartIndex": number } ], "ResultItems": [ { "Highlights": { "Address": { "Label": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ] }, "Title": [ { "EndIndex": number, "StartIndex": number, "Value": "string" } ] }, "Place": { "AccessPoints": [ { "Position": [ number ] } ], "AccessRestrictions": [ { "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Restricted": boolean } ], "Address": { "AddressNumber": "string", "Block": "string", "Building": "string", "Country": { "Code2": "string", "Code3": "string", "Name": "string" }, "District": "string", "Intersection": [ "string" ], "Label": "string", "Locality": "string", "PostalCode": "string", "Region": { "Code": "string", "Name": "string" }, "SecondaryAddressComponents": [ { "Designator": "string", "Number": "string" } ], "Street": "string", "StreetComponents": [ { "BaseName": "string", "Direction": "string", "Language": "string", "Prefix": "string", "Suffix": "string", "Type": "string", "TypePlacement": "string", "TypeSeparator": "string" } ], "SubBlock": "string", "SubDistrict": "string", "SubRegion": { "Code": "string", "Name": "string" } }, "BusinessChains": [ { "Id": "string", "Name": "string" } ], "Categories": [ { "Id": "string", "LocalizedName": "string", "Name": "string", "Primary": boolean } ], "Distance": number, "FoodTypes": [ { "Id": "string", "LocalizedName": "string", "Primary": boolean } ], "MapView": [ number ], "Phonemes": { "Address": { "Block": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Country": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "District": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Locality": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Region": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "Street": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubBlock": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubDistrict": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ], "SubRegion": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "Title": [ { "Language": "string", "Preferred": boolean, "Value": "string" } ] }, "PlaceId": "string", "PlaceType": "string", "PoliticalView": "string", "Position": [ number ], "TimeZone": { "Name": "string", "Offset": "string", "OffsetSeconds": number } }, "Query": { "QueryId": "string", "QueryType": "string" }, "SuggestResultItemType": "string", "Title": "string" } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_geoplaces_Suggest_ResponseSyntax) ** The pricing bucket for which the query is charged at. For more information on pricing, please visit [Amazon Location Service Pricing](https://aws.amazon.com/location/pricing/). The following data is returned in JSON format by the service. ** [QueryRefinements](#API_geoplaces_Suggest_ResponseSyntax) ** Maximum number of query terms to be returned for use with a search text query. Not available in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of [QueryRefinement](API_geoplaces_QueryRefinement.md) objects Array Members: Minimum number of 0 items. Maximum number of 10 items. ** [ResultItems](#API_geoplaces_Suggest_ResponseSyntax) ** List of places or results returned for a query. Type: Array of [SuggestResultItem](API_geoplaces_SuggestResultItem.md) objects Array Members: Minimum number of 0 items. Maximum number of 100 items. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** AccessDeniedException ** You don't have sufficient access to perform this action. HTTP Status Code: 403 ** InternalServerException ** The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 ** ThrottlingException ** The request was denied due to request throttling. HTTP Status Code: 429 ** ValidationException ** The input fails to satisfy the constraints specified by an AWS service. ** FieldList ** Test stub for FieldList. ** Reason ** Test stub for reason HTTP Status Code: 400 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-places-2020-11-19/Suggest) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-places-2020-11-19/Suggest) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-places-2020-11-19/Suggest) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-places-2020-11-19/Suggest) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-places-2020-11-19/Suggest) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-places-2020-11-19/Suggest) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-places-2020-11-19/Suggest) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-places-2020-11-19/Suggest) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-places-2020-11-19/Suggest) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-places-2020-11-19/Suggest)