Work with location search

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

Add location search functionality on a map

First, make sure you've provisioned a search index resource and configured your app using the instructions in either Configure Location Search or Use existing Amazon Location Service resources and you have already setup displaying a map in your application.

Note: For React, you can use the Amplify UI Location Search component to generate and display the search results.

To add a location search UI component to your map, you can use the maplibre-gl-geocoder library. maplibre-gl-js-amplify package makes it easy to integrate maplibre-gl-geocoder with Amplify Geo by exporting a utility function createAmplifyGeocoder() that returns an instance of maplibre-gl-geocoder with some pre-defined settings and supports all the options for customizing the UI component

Install the necessary dependencies with the following command:

1npm install @maplibre/maplibre-gl-geocoder maplibre-gl@1 maplibre-gl-js-amplify

Note: Make sure that maplibre-gl-js-amplify version 4.0.0 or above is installed.

First, create a map onto which you want to add the location search UI component. See the guide on creating and displaying maps.

Then, use createAmplifyGeocoder() to get a new instance of MaplibreGeocoder and add the location search UI component to the map.

Note: Ensure that your package bundler (webpack, rollup, etc) is configured to handle css files. Check out the webpack documentation here.

1import { createMap, createAmplifyGeocoder } from "maplibre-gl-js-amplify";
2import maplibregl from "maplibre-gl";
3import "maplibre-gl/dist/maplibre-gl.css";
4import "@maplibre/maplibre-gl-geocoder/dist/maplibre-gl-geocoder.css";
5import "maplibre-gl-js-amplify/dist/public/amplify-geocoder.css"; // Optional CSS for Amplify recommended styling
6
7async function initializeMap() {
8    const el = document.createElement("div");
9    el.setAttribute("id", "map");
10    document.body.appendChild(el);
11
12    const map = await createMap({
13        container: "map",
14        center: [-123.1187, 49.2819], // [Longitude, Latitude]
15        zoom: 11,
16    })
17
18    map.addControl(createAmplifyGeocoder());
19}
20
21initializeMap();

You can also use maplibre-gl-geocoder to display the location search UI component anywhere in your application, even outside the map.

To do so, extract the html element using function onAdd() and attach it anywhere in your DOM instead of adding it via the map's addControl() function.

1const geocoder = createAmplifyGeocoder();
2document.getElementById("search").appendChild(geocoder.onAdd());

Customize Search Icons

You can customize the search icons used by the maplibre-gl-geocoder to use any image of your choosing. MapLibre markers require an HTMLElement when passing in custom images.

The following example puts an existing SVG icon into an HTMLElement before being passed to createAmplifyGeocoder which creates a maplibre-gl-geocoder.

1import myIcon from "./myIcon.svg" // relative path to your custom icon
2
3const icon = new Image(100, 100);
4icon.src = myIcon;
5
6const geocoder = createAmplifyGeocoder({ showResultMarkers: { element: icon } });
7map.addControl(geocoder);

A search box

Location-based search capabilities

Amplify Geo enables you to search for locations by text, addresses, or geo-coordinates.

Search by text, address, business name, city, and more

The Geo.searchByText() API enables you to search for places or points of interest by free-form text, such as an address, name, city, or region.

1import { Geo } from "@aws-amplify/geo"
2
3Geo.searchByText("Amazon Go Store")

Customize your search results further by providing:

countries - to limit the search results to given countries (specified in ISO Alpha-3 country codes)
maxResults - to limit the maximum result set
biasPosition - to act as the search origination location
searchAreaConstraints - to limit the area to search inside of
searchIndexName - to use a different Location Service search index resource than the default

Note: Providing both biasPosition and searchAreaConstraints parameters simultaneously returns an error.

1const searchOptionsWithBiasPosition = {
2  countries: string[], // Alpha-3 country codes
3  maxResults: number, // 50 is the max and the default
4  biasPosition: [
5    longitude // number
6    latitude // number,
7  ], // Coordinates point to act as the center of the search
8  searchIndexName: string, // the string name of the search index
9}
10
11const searchOptionsWithSearchAreaConstraints = {
12  countries: ["USA"], // Alpha-3 country codes
13  maxResults: 25, // 50 is the max and the default
14  searchAreaConstraints: [SWLongitude, SWLatitude, NELongitude, NELatitude], // Bounding box to search inside of
15  searchIndexName: string, // the string name of the search index
16}
17
18Geo.searchByText('Amazon Go Stores', searchOptionsWithBiasPosition)

This returns places and their coordinates that match the search constraints. A place can also have additional metadata as shown in the example below.

1// returns
2[
3  {
4    geometry: {
5      point:
6        [
7          -122.34014899999994, // Longitude point
8          47.61609000000004 // Latitude point
9        ],
10    },
11    addressNumber: "2131" // optional string for the address number alone
12    country: "USA" // optional Alpha-3 country code
13    label: "Amazon Go, 2131 7th Ave, Seattle, WA, 98121, USA" // Optional string
14    municipality: "Seattle" // Optional string
15    neighborhood: undefined // Optional string
16    postalCode: "98121" // Optional string
17    region: "Washington" // Optional string
18    street: "7th Ave" // Optional string
19    subRegion: "King County" // Optional string
20  }
21]

Search by coordinates

The Geo.searchByCoordinates() API is a reverse Geocoder that takes a coordinate point and returns information about what it finds at that point on the map. The returned object is the same shape as searchByText() API above.

1import { Geo } from "@aws-amplify/geo";
2
3Geo.searchByCoordinates([longitudePoint, latitudePoint])

You can optionally limit your result set with the maxResults parameter or override the default search index with the searchIndexName parameter.

1const searchOptionsWithBiasPosition = {
2  maxResults: number, // 50 is the max and the default
3  searchIndexName: string, // the string name of the search index
4}
5
6Geo.searchByCoordinates([-122.3399573, 47.616179], searchOptionsWithBiasPosition)

Search for suggestions

The Geo.searchForSuggestions() API enables you to search for suggestions by free-form text, such as a place, address, city, or region.

1import { Geo } from "@aws-amplify/geo";
2
3Geo.searchForSuggestions("Amazon Go Store")

Similar to Geo.searchByText() API, customize your search results further by providing:

countries - to limit the search results to given countries (specified in ISO Alpha-3 country codes)
maxResults - to limit the maximum result set
biasPosition - to act as the search origination location
searchAreaConstraints - to limit the area to search inside of
searchIndexName - to use a different Location Service search index resource than the default

Note: Providing both biasPosition and searchAreaConstraints parameters simultaneously returns an error.

1const searchOptionsWithBiasPosition = {
2  countries: string[], // Alpha-3 country codes
3  maxResults: number, // 50 is the max and the default
4  biasPosition: [
5    longitude // number
6    latitude // number,
7  ], // Coordinates point to act as the center of the search
8  searchIndexName: string, // the string name of the search index
9}
10
11const searchOptionsWithSearchAreaConstraints = {
12  countries: ["USA"], // Alpha-3 country codes
13  maxResults: 25, // 50 is the max and the default
14  searchAreaConstraints: [SWLongitude, SWLatitude, NELongitude, NELatitude], // Bounding box to search inside of
15  searchIndexName: string, // the string name of the search index
16}
17
18Geo.searchForSuggestions('Amazon Go', searchOptionsWithBiasPosition)

This returns a list of suggestions (places and their respective placeId if available) that match the search constraints.

1// returns
2[
3  {
4    text: "Amazon Go, 2131 7th Ave, Seattle, WA, 98121, USA",
5    placeId: "8fd9d4c6-2527-4190-a7df-0dae352c9dc6"
6  },
7  {
8    text: "Amazon Go, 1906 Terry Ave, Seattle, WA, 98101, USA",
9    placeId: "5d04d071-dea2-4d86-bfce-86bd6a8f4787"
10  }
11]

In cases where placeId is not available on the list of suggestions as below, use searchByText to search for the selected place by text.

1Geo.searchForSuggestions("Amazon", { MaxResults: 5 })
2
3// returns
4[
5  {
6    text: "Amazon Go",
7  },
8  {
9    text: "Amazon 4-star",
10  }
11]
12
13Geo.searchByText('Amazon Go', { MaxResults: 5 })

This returns places and their coordinates that match the search text.

Search by PlaceId

The Geo.searchByPlaceId() API enables you to search for a place by a placeId, which is a unique opaque token for a place returned by the provider.

Note: Upgrade to the latest Amplify CLI version (greater than version 12.5.1) and do an amplify push to update your IAM policies to allow for getPlace API.

1import { Geo } from "@aws-amplify/geo";
2
3Geo.searchByPlaceId(placeId)

You can optionally override the default search index with the searchIndexName parameter.

1const searchByPlaceIdOptions = {
2  searchIndexName: string, // the string name of the search index
3}
4
5Geo.searchByPlaceId("8fd9d4c6-2527-4190-a7df-0dae352c9dc6", searchByPlaceIdOptions)

This returns a place with metadata as shown in the example below.

1// returns
2{
3  geometry: {
4    point:
5      [
6        -122.34014899999994, // Longitude point
7        47.61609000000004 // Latitude point
8      ],
9  },
10  addressNumber: "2131" // optional string for the address number alone
11  country: "USA" // optional Alpha-3 country code
12  label: "Amazon Go, 2131 7th Ave, Seattle, WA, 98121, USA" // Optional string
13  municipality: "Seattle" // Optional string
14  neighborhood: undefined // Optional string
15  postalCode: "98121" // Optional string
16  region: "Washington" // Optional string
17  street: "7th Ave" // Optional string
18  subRegion: "King County" // Optional string
19}

Configure location search

Configure a geofence collection