Work with location search
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.
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
version1.1.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 styling6
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: 1116 });17
18 map.addControl(createAmplifyGeocoder());19}20
21initializeMap();
Display the location search box outside the map
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 icon2
3const icon = new Image(100, 100);4icon.src = myIcon;5
6const geocoder = createAmplifyGeocoder({7 showResultMarkers: { element: icon }8});9map.addControl(geocoder);
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';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 defaultNote: Providing both
biasPosition
andsearchAreaConstraints
parameters simultaneously returns an error.
1const searchOptionsWithBiasPosition = {2 countries: string[], // Alpha-3 country codes3 maxResults: number, // 50 is the max and the default4 biasPosition: [5 longitude // number6 latitude // number,7 ], // Coordinates point to act as the center of the search8 searchIndexName: string, // the string name of the search index9}10
11const searchOptionsWithSearchAreaConstraints = {12 countries: ["USA"], // Alpha-3 country codes13 maxResults: 25, // 50 is the max and the default14 searchAreaConstraints: [SWLongitude, SWLatitude, NELongitude, NELatitude], // Bounding box to search inside of15 searchIndexName: string, // the string name of the search index16}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// returns2[3 {4 geometry: {5 point:6 [7 -122.34014899999994, // Longitude point8 47.61609000000004 // Latitude point9 ],10 },11 addressNumber: "2131" // optional string for the address number alone12 country: "USA" // optional Alpha-3 country code13 label: "Amazon Go, 2131 7th Ave, Seattle, WA, 98121, USA" // Optional string14 municipality: "Seattle" // Optional string15 neighborhood: undefined // Optional string16 postalCode: "98121" // Optional string17 region: "Washington" // Optional string18 street: "7th Ave" // Optional string19 subRegion: "King County" // Optional string20 }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';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 default3 searchIndexName: string // the string name of the search index4};5
6Geo.searchByCoordinates(7 [-122.3399573, 47.616179],8 searchOptionsWithBiasPosition9);
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';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 defaultNote: Providing both
biasPosition
andsearchAreaConstraints
parameters simultaneously returns an error.
1const searchOptionsWithBiasPosition = {2 countries: string[], // Alpha-3 country codes3 maxResults: number, // 50 is the max and the default4 biasPosition: [5 longitude // number6 latitude // number,7 ], // Coordinates point to act as the center of the search8 searchIndexName: string, // the string name of the search index9}10
11const searchOptionsWithSearchAreaConstraints = {12 countries: ["USA"], // Alpha-3 country codes13 maxResults: 25, // 50 is the max and the default14 searchAreaConstraints: [SWLongitude, SWLatitude, NELongitude, NELatitude], // Bounding box to search inside of15 searchIndexName: string, // the string name of the search index16}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// returns2[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 // returns3 ({4 text: 'Amazon Go'5 },6 {7 text: 'Amazon 4-star'8 })9];10
11Geo.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.
1import { Geo } from 'aws-amplify';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 index3};4
5Geo.searchByPlaceId(6 '8fd9d4c6-2527-4190-a7df-0dae352c9dc6',7 searchByPlaceIdOptions8);
This returns a place with metadata as shown in the example below.
1// returns2{3 geometry: {4 point:5 [6 -122.34014899999994, // Longitude point7 47.61609000000004 // Latitude point8 ],9 },10 addressNumber: "2131" // optional string for the address number alone11 country: "USA" // optional Alpha-3 country code12 label: "Amazon Go, 2131 7th Ave, Seattle, WA, 98121, USA" // Optional string13 municipality: "Seattle" // Optional string14 neighborhood: undefined // Optional string15 postalCode: "98121" // Optional string16 region: "Washington" // Optional string17 street: "7th Ave" // Optional string18 subRegion: "King County" // Optional string19}