export const meta = {
  title: `Location Search`,
  description: `Use Amplify CLI to create and manage location search indices or place indices that are used to search for places in your application.`,
};

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

<Callout>

**Note:** Please reach out to us for any feedback and/or issues [here](https://github.com/aws-amplify/amplify-cli/issues)

</Callout>

## 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:

```bash
amplify add geo
```
```console
? Select which capability you want to add:
  Map (visualize the geospatial data)
> 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:

```console
? Provide a name for the location search index (place index):
> 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.

```console
? Who can access this Search Index?
❯ Authorized users only
  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](https://docs.aws.amazon.com/location/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-search-for-place).

<Callout>

**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.

</Callout>

## 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](https://aws.amazon.com/location/pricing/) along with the [location service terms](https://aws.amazon.com/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.
```bash
"geo": {
    "MyPlaceIndex": {
      "isDefault": true,
      "providerPlugin": "awscloudformation",
      "service": "PlaceIndex",
      "dataProvider": "Esri",
      "dataSourceIntendedUse": "SingleUse",
      "pricingPlan": "MobileAssetManagement",
      "accessType": "AuthorizedUsers"
    }
}
```

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


<Callout>

**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.

</Callout>

## 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](https://docs.aws.amazon.com/location/latest/developerguide/what-is-data-provider.html).

```console
? Specify the data provider of geospatial data for this Search Index:
  Esri
❯ HERE
```

<Callout>

**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](https://aws.amazon.com/service-terms/) for more details.

</Callout>

`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.

```console
? Do you want to cache or store the results of search operations?
> No
```

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

Refer [this location service doc](https://docs.aws.amazon.com/location-places/latest/APIReference/API_DataSourceConfiguration.html#locationplaces-Type-DataSourceConfiguration-IntendedUse) 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:

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

Answering `No` will retain the previously set default.

That's it! You can now render maps in your application. Follow the library documentation as listed [here](/lib/geo/search).
