Page updated Jan 16, 2024

Configure location search

Amplify's geo category enables you to search by places, addresses, and coordinates in your app with "place index" resources.

Note: Please reach out to us for any feedback and/or issues here

Setup a new Location Search Index

You can add a new location search index by running the following command from your project's root folder:

amplify add geo
1amplify add geo
? Select which capability you want to add: Map (visualize the geospatial data) > Location search (search by places, addresses, coordinates)
1? Select which capability you want to add:
2 Map (visualize the geospatial data)
3> Location search (search by places, addresses, coordinates)

If you haven't set up the auth category already, the Amplify CLI will guide you to enable the auth category. The auth category is required in your application so that the appropriate permissions to search for places can be given to Authorized and/or Guest users as described below.

Next, set a name for the location search index:

? Provide a name for the location search index (place index): > MyPlaceIndex
1? Provide a name for the location search index (place index):
2> MyPlaceIndex

Location Search Access permissions

Next, configure the access permissions for your location search index and authorize users to search for places. You can scope permissions based on an individual user's authentication status.

? Who can access this Search Index? ❯ Authorized users only Authorized and Guest users
1? Who can access this Search Index?
2❯ Authorized users only
3 Authorized and Guest users

Select Authorized users only if only authenticated users can search for places.

Select Authorized and Guest users if both authenticated and unauthenticated users can can search for places.

For more information, refer link to location service page.

Note: If you are using Amplify CLI version 7.6.19 or older and have a Search Index added to your application, please follow these instructions to get the auto-complete suggestions for search:

  1. Upgrade the Amplify CLI to version 7.6.20 or later using npm i -g @aws-amplify/cli.
  2. Run amplify update geo and select the existing Search Index. Choose the same configuration for the Search Index that you already have.
  3. Run amplify push to update the backend resource.

Location Search Index Pricing Plan

The pricing plan for Search Index will be set to RequestBasedUsage. We advice you to go through the location service pricing along with the location service terms (82.5 section) to learn more about the pricing plan.

Update Location Search Index pricing plan to RequestBasedUsage

You can check the pricing plan for your Search Index from geo/<searchIndexID>/pricingPlan attribute in your project metadata file located at amplify/backend/amplify-meta.json in your project.

"geo": { "MyPlaceIndex": { "isDefault": true, "providerPlugin": "awscloudformation", "service": "PlaceIndex", "dataProvider": "Esri", "dataSourceIntendedUse": "SingleUse", "pricingPlan": "MobileAssetManagement", "accessType": "AuthorizedUsers" } }
1"geo": {
2 "MyPlaceIndex": {
3 "isDefault": true,
4 "providerPlugin": "awscloudformation",
5 "service": "PlaceIndex",
6 "dataProvider": "Esri",
7 "dataSourceIntendedUse": "SingleUse",
8 "pricingPlan": "MobileAssetManagement",
9 "accessType": "AuthorizedUsers"
10 }
11}

You can check your Amplify CLI version using amplify -v.

Note: If you are using Amplify CLI version 7.6.8 or older and have a Search Index added to your application with the pricing plan set to MobileAssetTracking or MobileAssetManagement, please follow these instructions to update the pricing plan:

  1. Upgrade the Amplify CLI to version 7.6.9 or later using npm i -g @aws-amplify/cli.
  2. Run amplify update geo and select the Search Index with Asset based pricing plan. Choose the same configuration for the Search Index that you already have.
  3. Run amplify push to update the backend resource.

Advanced Settings

You can optionally configure the data provider and result storage location for your location search index.

Location Search data provider

You can select a data provider as the source for geocoding, reverse geocoding and searches. Each provider gathers and curates their data using different means. They may also have varying expertise in different regions of the world. The available data providers of geospatial data are shown. To learn more about data providers, please refer this location service doc.

? Specify the data provider of geospatial data for this Search Index: Esri ❯ HERE
1? Specify the data provider of geospatial data for this Search Index:
2 Esri
3❯ HERE

Note: If your application is tracking or routing assets you use in your business (such as delivery vehicles or employees), you may only use HERE as your geolocation provider. See section 82 of the AWS service terms for more details.

HERE will be set as default data provider for the location search index, if you do not want to explicitly set this property.

Location Search result storage location

You can specify how the results of a search operation will be stored by the caller.

? Do you want to cache or store the results of search operations? > No
1? Do you want to cache or store the results of search operations?
2> No

No will be chosen as default if the developer does not want to explicitly set this property.

Refer this location service doc for more information.

Set a default Location Search Index

If you added more than one location search index via amplify add geo, the index that was added last will be the default. However, you can choose if the current search index should be the default one used in your application:

Set this search index as the default? It will be used in Amplify Search API calls if no explicit reference is provided. > No
1Set this search index as the default? It will be used in Amplify Search API calls if no explicit reference is provided.
2> No

Answering No will retain the previously set default.

That's it! You can now search in your application. Follow the documentation for working with search as listed here.