Autocomplete - Amazon Location Service
Using autocompleteUsing the autocomplete resultsAutocomplete near a positionAutocomplete within a bounding boxAutocomplete within a countryExample response

Autocomplete

Autocomplete provides responsive feedback to end users as they are typing their search query. It provides suggestions for addresses and points of interest based on partial or misspelled free-form text. You can use place index resources to request autocomplete suggestions, and display the resulting suggestions in your application.

Amazon Location does not support storage of autocomplete suggestions. An error is returned if the place index used for an autocomplete call is configured for use with stored geocodes. To use stored geocodes and query for suggestions, create and configure multiple place indexes.

This section describes how to send an autocomplete request. It starts with the most basic form of the request, and then shows optional parameters that you can use to increase the relevance of autocomplete search results.

Using autocomplete

You can submit a simple request for autocomplete suggestions by using the SearchPlaceIndexForSuggestions operation. The simplest form of the request has a single required parameter, the query Text:

  • Text – The free-form partial text to use to generate place suggestions. For example, the string eiffel tow.

To limit the number of results returned, add the optional MaxResults parameter:

  • MaxResults – Limits the number of results returned in the query response.

You can use the Amazon Location APIs or the AWS CLI.

API

The following example is a SearchPlaceIndexForSuggestions request to search the place index resource, ExamplePlaceIndex, for up to 5 suggestions based on the partial place name kamp. 

POST /places/v0/indexes/ExamplePlaceIndex/search/suggestions
Content-type: application/json

{
    "Text": "kamp",
    "MaxResults": 5
}
AWS CLI

The following example is a search-place-index-for-suggestions command to search the place index resource, ExamplePlaceIndex, for up to 5 suggestions based on the partial place name kamp. 

aws location \
              search-place-index-for-suggestions \
              --index-name ExamplePlaceIndex \
              --text kamp \
              --max-results 5

The call to SearchPlaceIndexForSuggestions results in a list of places with a name and an ID for each. You can use those results to present suggestions of what the user might be searching for, as they are typing, such as providing a dropdown list of choices underneath a text box. For example, here are the results for suggestions, based on a user typing kamp.

{
    "Summary": {
        "Text": "kamp",
        "MaxResults": 5,
        "DataSource": "Esri"
    },
    "Results": [
        {
            "Text": "Kampuchea",
            "PlaceId": "AQAAAIAADsn2T3KdrRWeaXLeVEyjNx_JfeTsMB0NVCEAnAZoJ-o3nqdlJZAdgcT2oWi1w9pS4wXXOk3O1vsKlGsPyHjV4EJxsu289i3hVO_BUPgP7SFoWAi8BW2v7LvAjQ5NfUPy7a1v9ajT3feIqcUZszWSTqKbJHFYvQqW7wdqhpQq3Wy-et39ZQDWSPLZUzgcjN-6VD2gyKkH0Po7gSm8YSJNSQ"
        },
        {
            "Text": "Kampoul, Kabul, AFG",
            "PlaceId": "AQAAAIAAA1mxl_-9ffzXD07rBgo9fh6E01Pd1YKvuT5rz2qBDxqBkhTlgkeiOPR2s5sa3YBLxUqQI8bhymsYcu9R-DkX3L9QSi3CB5LhNPu160iSFJo6H8S1CrxO3QsJALhrr9mdbg0R4R4YDywkhkeBlnbn7g5C5LI_wYx873WeQZuilwtsGm8jcMA0Ya5oK4netQC6piVx6zmnPdwBs-UeXcb_bg"
        },
        {
            "Text": "Kampala, UGA",
            "PlaceId": "AQAAAIAAzZfZt3qMruKGObyhP6MM0pqy2L8SULlVWT7a3ertLBRS6Q5n7I4s9D7E0nRHADAj7mL7kvX1Q8HD-mpuiATXNJ1Ix4_V_1B15zHe8jlYKMWvXbgbO8cMpgR2fqYqZMR1x-dfBOO8OoqujKZldvPIDK1kNe3GwcaqvvMWWPMeaGd203brFynubAe-MmFF-Gjz-WBMfUy9og6MV7bkk6NGCA"
        },
        {
            "Text": "Kampar, Riau, IDN",
            "PlaceId": "AQAAAIAAvbXXx-srOi111tHOkPdao0GF7WQ_KaZ444SEnevycp6Gtf_2JWgPfCE5bIQCYwya1uZQpX2a8YJoFm2K7Col4fLu7IK0yYOLhZx4kp6QzbG4xEAGzfWtWq6nfbb0lZfuHY6r0g1sRlN1aucvwim4AEcKRzckqaa93JI8064pj6Q59kN37pAa3JX4ayEzH1DzIL3m3oqxzd4O16yGfhAIgA"
        },
        {
            "Text": "Kampung Pasir Gudang Baru, Johor, MYS",
            "PlaceId": "AQAAAIAA4HLQHdjUDcaaXLE9wtNIT1cjQYLgkBnMoG2eNN0AaQ8PJoWabLRXmmPUaAj8MAD6vT0i6zqaun5Mixyj7vnYXrk2xp59cbgdqvQaPoWhSCVxBOX0WGs3cZ8TnIRn3c-6v8_UfmqC7es1gUyECfMGK04VBKiwpHwCzjNsqymkd9BC3A9K3QlMgd3dkrGjv_vV94iLlnFTbaecrckl2UDCkA"
        }
    ]
}

The next section explains how to use the PlaceID from these results.

Using the autocomplete results

The call to SearchPlaceIndexForSuggestions results in a list of places with a name and an ID for each. You can use those results to present suggestions of what the user might be searching for, as they are typing, such as providing a dropdown list of choices underneath a text box. When the user chooses one of the results, you can then call the GetPlace operation with the ID of their selection to return the details of that place, including location, address, or other details.

Note

A PlaceId is valid only if all of the following are the same in the original search request, and the call to GetPlace.

  • Customer AWS account

  • AWS Region

  • Data provider specified in the place index resource

Typically, you use GetPlace with the Amazon Location APIs. The following example is a GetPlace request to find one of the suggestions from the previous section. This example is based on the partial place name kamp. 

POST /places/v0/indexes/ExamplePlaceIndex/places/AQAAAIAADsn2T3KdrRWeaXLeVEyjNx_JfeTsMB0NVCEAnAZoJ-o3nqdlJZAdgcT2oWi1w9pS4wXXOk3O1vsKlGsPyHjV4EJxsu289i3hVO_BUPgP7SFoWAi8BW2v7LvAjQ5NfUPy7a1v9ajT3feIqcUZszWSTqKbJHFYvQqW7wdqhpQq3Wy-et39ZQDWSPLZUzgcjN-6VD2gyKkH0Po7gSm8YSJNSQ

Autocomplete near a position

When you search for autocomplete place suggestions by using SearchPlaceIndexForSuggestions, you can get more locally-relevant suggestions by adding the following optional parameter:

  • BiasPosition – The position you want to search nearby. Defined as [longitude, latitude].

The following example uses a SearchPlaceIndexForSuggestions request to search the place index resource ExamplePlaceIndex for place suggestions matching the partial query kamp near the position [32.5827,0.3169]. 

POST /places/v0/indexes/ExamplePlaceIndex/search/suggestions
Content-type: application/json

{
    "Text": "kamp",
    "BiasPosition": [32.5827,0.3169]
}

The suggestions returned for the same Text can be different if a different BiasPosition is chosen, such as [-96.7977, 32.7776].

Autocomplete within a bounding box

You can narrow your autocomplete search to receive only suggestions for places which are located within a given boundary by adding the following optional parameter:

  • FilterBBox – A bounding box that you specify to filter your results to coordinates within the box's boundaries. Defined as [LongitudeSW, LatitudeSW, LongitudeNE, LatitudeNE]

    Note

    A request can't contain both the FilterBBox and BiasPosition parameters. Specifying both parameters in the request returns a ValidationException error.

The following example uses a SearchPlaceIndexForSuggestions request to search the place index resource ExamplePlaceIndex for place suggestions matching the partial query kamp, and which are contained within the bounding box where:

  • The longitude of the southwest corner of the bounding box is 32.5020.

  • The latitude of the southwest corner of the bounding box is 0.2678.

  • The longitude of the northeast corner of the bounding box is 32.6129.

  • The latitude of the northeast corner of the bounding box is 0.3502.

POST /places/v0/indexes/ExamplePlaceIndex/search/suggestions
Content-type: application/json

{
    "Text": "kamp",
    "FilterBBox": [
        32.5020, 0.2678,
        32.6129, 0.3502
    ]
}

The suggestions returned for the same Text are different if a different FilterBBox is chosen, such as [-97.9651, 32.0640, -95.1196, 34.0436].

Autocomplete within a country

You can narrow your autocomplete search to receive only suggestions for places which are located within a given country, or set of countries, by adding the following optional parameter:

  • FilterCountries – The countries you want to search for place suggestions within. You can specify up to 100 countries in one request using a ISO 3166 three-letter country code. For example, use AUS for Australia.

The following example uses a SearchPlaceIndexForSuggestions request to search the place index resource ExamplePlaceIndex for place suggestions matching the partial query kamp and which are contained within Uganda, Kenya, or Tanzania:

POST /places/v0/indexes/ExamplePlaceIndex/search/suggestions
Content-type: application/json

{
    "Text": "kamp",
    "FilterCountries": ["UGA", "KEN", "TZA"]
}

The suggestions returned for the same Text are different if a different FilterCountries list is chosen, such as ["USA"].

Example response

The following is an example response of suggested autocompletions for the SearchPlaceIndexForSuggestions operation, using the text kamp.

{
    "Summary": {
        "Text": "kamp",
        "MaxResults": 5,
        "DataSource": "Esri"
    },
    "Results": [
        {
            "Text": "Kampuchea",
            "PlaceId": "AQAAAIAADsn2T3KdrRWeaXLeVEyjNx_JfeTsMB0NVCEAnAZoJ-o3nqdlJZAdgcT2oWi1w9pS4wXXOk3O1vsKlGsPyHjV4EJxsu289i3hVO_BUPgP7SFoWAi8BW2v7LvAjQ5NfUPy7a1v9ajT3feIqcUZszWSTqKbJHFYvQqW7wdqhpQq3Wy-et39ZQDWSPLZUzgcjN-6VD2gyKkH0Po7gSm8YSJNSQ"
        },
        {
            "Text": "Kampoul, Kabul, AFG",
            "PlaceId": "AQAAAIAAA1mxl_-9ffzXD07rBgo9fh6E01Pd1YKvuT5rz2qBDxqBkhTlgkeiOPR2s5sa3YBLxUqQI8bhymsYcu9R-DkX3L9QSi3CB5LhNPu160iSFJo6H8S1CrxO3QsJALhrr9mdbg0R4R4YDywkhkeBlnbn7g5C5LI_wYx873WeQZuilwtsGm8jcMA0Ya5oK4netQC6piVx6zmnPdwBs-UeXcb_bg"
        },
        {
            "Text": "Kampala, UGA",
            "PlaceId": "AQAAAIAAzZfZt3qMruKGObyhP6MM0pqy2L8SULlVWT7a3ertLBRS6Q5n7I4s9D7E0nRHADAj7mL7kvX1Q8HD-mpuiATXNJ1Ix4_V_1B15zHe8jlYKMWvXbgbO8cMpgR2fqYqZMR1x-dfBOO8OoqujKZldvPIDK1kNe3GwcaqvvMWWPMeaGd203brFynubAe-MmFF-Gjz-WBMfUy9og6MV7bkk6NGCA"
        },
        {
            "Text": "Kampar, Riau, IDN",
            "PlaceId": "AQAAAIAAvbXXx-srOi111tHOkPdao0GF7WQ_KaZ444SEnevycp6Gtf_2JWgPfCE5bIQCYwya1uZQpX2a8YJoFm2K7Col4fLu7IK0yYOLhZx4kp6QzbG4xEAGzfWtWq6nfbb0lZfuHY6r0g1sRlN1aucvwim4AEcKRzckqaa93JI8064pj6Q59kN37pAa3JX4ayEzH1DzIL3m3oqxzd4O16yGfhAIgA"
        },
        {
            "Text": "Kampung Pasir Gudang Baru, Johor, MYS",
            "PlaceId": "AQAAAIAA4HLQHdjUDcaaXLE9wtNIT1cjQYLgkBnMoG2eNN0AaQ8PJoWabLRXmmPUaAj8MAD6vT0i6zqaun5Mixyj7vnYXrk2xp59cbgdqvQaPoWhSCVxBOX0WGs3cZ8TnIRn3c-6v8_UfmqC7es1gUyECfMGK04VBKiwpHwCzjNsqymkd9BC3A9K3QlMgd3dkrGjv_vV94iLlnFTbaecrckl2UDCkA"
        }
    ]
}