AWS location documentation change
Summary
Revised Autocomplete API documentation with updated authentication details, response attribute requirements, usage notes, and structural clarifications.
Security assessment
The changes clarify authentication methods (API keys vs. SigV4) and their appropriate use cases, which are security-related features. However, there is no evidence of addressing a specific security vulnerability. The updates improve documentation around secure authentication practices but do not indicate a security fix.
Diff
diff --git a/location/latest/developerguide/autocomplete.md b/location/latest/developerguide/autocomplete.md index 9715cc6be..6de9c0ea0 100644 --- a//location/latest/developerguide/autocomplete.md +++ b//location/latest/developerguide/autocomplete.md @@ -9,3 +9 @@ Use casesUnderstand the requestUnderstand the response -The Autocomplete API completes potential places and addresses as the user types, based on partial input. It enhances the efficiency and accuracy of address entry by completing queries with valid address information after a few keystrokes. Additionally, Autocomplete supports result filtering based on geographic location, country, or specific place types and can be tailored using optional parameters such as language and political view. - -By default, Autocomplete returns only the `ID` and `Title` fields, providing a cost-effective option. Additional address components and highlights can be requested by setting `additionalFeatures` to `Core`. +`Autocomplete` returns complete addresses and address components based on partial input. Key use cases include address form auto-filling and typeahead address completion (completing the address interactively while the end user is typing it). @@ -15,5 +13 @@ By default, Autocomplete returns only the `ID` and `Title` fields, providing a c - * Refer to [Places pricing](./places-pricing.html) for cost details associated with stored results. - - * Autocomplete does not return geocodes. - - * Autocomplete does not support premium Japan data. +By default, only the place ID, place type, and label attributes are returned for each result. Rich additional detail, including the full address breakdown and input highlight ranges for interactive use cases can be obtained by setting the `AdditionalFeatures` input attribute, but note that requesting additional features may impact [Places pricing](./places-pricing.html) @@ -20,0 +15 @@ By default, Autocomplete returns only the `ID` and `Title` fields, providing a c +###### Note @@ -21,0 +17 @@ By default, Autocomplete returns only the `ID` and `Title` fields, providing a c +Japanese addresses are not supported. @@ -22,0 +19 @@ By default, Autocomplete returns only the `ID` and `Title` fields, providing a c +Results are always addresses, or address components such as streets, postal codes, and countries. Points of interest are never returned. Results do not include geocodes, since `Autocomplete` is focused on address completion, not geocoding. To get address geocode coordinates, use the [Geocode](https://docs.aws.amazon.com/location/latest/developerguide/geocode.html) operation.Results can be filtered by geographic area. They can also be filtered by place type, for example to include only localities or only postal codes. @@ -24 +21 @@ By default, Autocomplete returns only the `ID` and `Title` fields, providing a c -For more information, see [Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) in the _Amazon Location Service API Reference_. +For full details on all the Autocomplete request and response attributes, please, see[Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) in the _Amazon Location Service API Reference_. @@ -30 +27 @@ For example requests, responses, cURL, and CLI commands for this API, see [How t - * **Enhance checkout experience:** Provide real-time address completion as customers enter their location on websites or apps. Ensure that delivery or pickup locations match known addresses to streamline address validation, reduce errors, and create a seamless checkout experience. + * **Enhance checkout experience:** Provide real-time address completion as customers enter their addresses in e-commerce checkout experiences and other address entry experiences on websites or apps. Ensure that delivery or pick-up locations match known addresses, reducing costly errors and increasing customer satisfaction. @@ -32 +29 @@ For example requests, responses, cURL, and CLI commands for this API, see [How t - * **Support customer services:** Offer real-time address suggestions for customer services such as contact centers or emergency services, streamlining the process of locating accurate addresses and improving user satisfaction by reducing the time needed to obtain correct address information. + * **Support customer services:** Give real-time address suggestions to customer service representatives in fields such as contact centers and emergency service dispatching, streamlining the process of collecting accurate address information and improving user satisfaction by reducing the time needed to obtain correct address information. @@ -39 +36 @@ For example requests, responses, cURL, and CLI commands for this API, see [How t -The Autocomplete request uses optional parameters to refine search results. For more details, refer to the Autocomplete API Reference. +The `Autocomplete` operation supports many optional request attributes to refine the search results. For the complete list of request attributes, refer to [Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) in the _Amazon Location Service API Reference_. @@ -46 +43 @@ The request accepts the following key parameters: -The `Key` parameter is optional if other authentication methods are used. +The Autocomplete API operation supports two alternative authentication modes. You can authenticate either by signing the request with a [SigV4 signature](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) or by providing an [API Key](https://docs.aws.amazon.com/location/latest/developerguide/access.html). @@ -48 +45 @@ The `Key` parameter is optional if other authentication methods are used. - * `Key`: Optional parameter for authentication. + * If you are making requests using a language-specific AWS SDK or using the AWS CLI, your request will normally be signed with SigV4 by default. @@ -49,0 +47 @@ The `Key` parameter is optional if other authentication methods are used. + * In some use cases, for example, making requests from a web browser or using some other non-AWS SDK client, API keys are a more appropriate form of authentication. Use the optional Key request attribute to provide an API key for authenticating to `Autocomplete`. @@ -53 +50,0 @@ The `Key` parameter is optional if other authentication methods are used. -For more information, see [Authenticate with Amazon Location Service](./access.html) @@ -55 +52 @@ For more information, see [Authenticate with Amazon Location Service](./access.h -**Querying** +For more information, see [Authenticate with Amazon Location Service](./access.html) in the _Amazon Location Service API Reference_. @@ -56,0 +54 @@ For more information, see [Authenticate with Amazon Location Service](./access.h +**Specifying the address to query** @@ -58 +55,0 @@ For more information, see [Authenticate with Amazon Location Service](./access.h -Defines the partial text query and geographic bias for result suggestions. @@ -60 +57 @@ Defines the partial text query and geographic bias for result suggestions. - * `QueryText`: The free-form text query used to find location results, this parameter is required. + * Use the mandatory `QueryText` request attribute to provide the free-form text to query. @@ -62 +59 @@ Defines the partial text query and geographic bias for result suggestions. - * `BiasPosition`: Suggests results closest to specified longitude and latitude coordinates, this parameter is optional. + * `BiasPosition`: Use the optional `BiasPosition` request attribute to provide a pin position, as a `[longitude, latitude]` coordinate pair, to improve the relevance of the returned results. @@ -67,3 +64 @@ Defines the partial text query and geographic bias for result suggestions. -For more information, see [Querying and biasing](./places-querying-biasing.html) - -**Refine results** +For more information, see [Querying and biasing](./places-querying-biasing.html) in the _Amazon Location Service API Reference_. @@ -70,0 +66 @@ For more information, see [Querying and biasing](./places-querying-biasing.html) +**Including all response attributes** @@ -72,3 +67,0 @@ For more information, see [Querying and biasing](./places-querying-biasing.html) -Applies filters to restrict results to specific countries or place types. - - * `Filter`: Allows filtering based on specified countries or place types. @@ -75,0 +69 @@ Applies filters to restrict results to specific countries or place types. +Set the optional field AdditionalFeatures to the value ["Core"] to include all available result attributes in the response, including the full address breakdown and interactive highlight locations. Note that requesting these extra attributes may impact [pricing](https://aws.amazon.com/location/pricing/) @@ -76,0 +71 @@ Applies filters to restrict results to specific countries or place types. +**Refine results** @@ -79 +74 @@ Applies filters to restrict results to specific countries or place types. -For more details, see [Filtering](./places-filtering.html) +Use the Filter attribute to filter the returned results based on specific countries, place types, or geographic areas. For more details, see [Filtering](./places-filtering.html) in the _Amazon Location Service Developer Guide_. @@ -83 +78 @@ For more details, see [Filtering](./places-filtering.html) -The Autocomplete API returns results as `ResultItems`, each representing a matched location based on the request parameters. For further details, refer to the Autocomplete API Reference. +The response object contains an array attribute named `ResultItems` that contains the list of results ranked in ascending order of relevance. For the full list of result item attributes, refer to [Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) in the _Amazon Location Service API Reference_. @@ -85 +80 @@ The Autocomplete API returns results as `ResultItems`, each representing a match -The response includes the following key data: +The following is a short list of some of the more important result item attributes. @@ -90 +85 @@ The response includes the following key data: -Contains detailed address components for each location. + * `PlaceType` contains the place type of the result, which tells us whether the address represents a point address, a street, etc. Results returned by `Autocomplete` will always have a place type that represents either a complete address or a component of an address, like a street or postal code. Results will never include points of interest. @@ -92 +87 @@ Contains detailed address components for each location. - * `Address`: Provides full address components, including street, postal code, and country. + * `Address` contains the result label and, if `["Core"]` is specified for `AdditionalFeatures`, it also contains the full breakdown of the address into structured fields including house number, street name, postal code, country, and the like.. @@ -102 +97 @@ Provides analysis data for each result in relation to the input query. - * `Distance`: Distance from the specified bias position to the result. + * `Distance`: If a `BiasPosition` was provided in the request, each result item contains a `Distance` attribute giving the distance, in meters, of that result from the `BiasPosition`. Requires `AdditionalFeatures` to be set to `["Core"]`. @@ -104 +99 @@ Provides analysis data for each result in relation to the input query. - * `Highlights`: Highlights portions of the query within the result for clarity. + * `Highlights` shows where words, phrases, and substrings from the input `QueryText` appear exactly in a result attribute, enabling applications to provide helpful user experiences that highlight matches for their users. Requires `AdditionalFeatures` to be set to `["Core"]`.