Migrate from Google Maps

Are you using Google Maps or another similar Map Provider and would like to switch over to using Amplify Geo or Amazon Location Service? This tutorial will show you how to take your existing Google Maps APIs and switch over to using Amplify Geo.

Getting Started

Amplify Geo provides APIs for using location based functionality. Under the hood Amplify uses Amazon Location Service and is designed to work with open source mapping library MapLibre.

This guide assumes that you are already familiar with the Google Maps JavaScript API and with front-end web development concepts including HTML, CSS, and JavaScript.

To complete this tutorial, you will need:

Amplify Geo
A text editor

Key differences between Amplify Geo and Google Maps

Coordinates Conventions

A key difference to notice between using Amplify Geo and Google Maps is with Google Maps Platform their convention for specifying coordinates is [lat, lng]. When migrating over to Amplify Geo the order is swapped to be [lng, lat]. This was done to match the geojson spec which is also used by MapLibre.

Authorization

When using Google Maps Platform or other similar services like Mapbox you will first be prompted to go to the Google Cloud Console to set up APIs and create an API key where you will then use the API key when requesting the Google Maps JS API. With Amplify Geo you will instead setup Amplify Auth using Amplify CLI and the MapView component will read the auth configuration from the amplifyconfiguration.json file. Behind the scenes Amplify Auth uses Amazon Cognito to set up client credentials with access to Location Service and Geo will use those credentials when making any location related API calls. More information on setting Amplify Auth and Geo can be found below in the Setting Up Amplify section.

Create a webpage

Open your text editor and create a new file called index.html.
Paste the following code into the file to set up the framework for a webpage with a map.

1<!DOCTYPE html>
2<html>
3
4<head>
5    <meta charset="utf-8">
6    <title>Display a map on a webpage</title>
7    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
8    <!-- Import MapLibre  -->
9    <script src="https://cdn.amplify.aws/packages/maplibre-gl/1.15.2/maplibre-gl.js"
10        integrity="sha384-rwYfkmAOpciZS2bDuwZ/Xa/Gog6jXem8D/whm3wnsZSVFemDDlprcUXHnDDUcrNU" crossorigin="anonymous"
11        referrerpolicy="no-referrer"></script>
12    <link href="https://cdn.amplify.aws/packages/maplibre-gl/1.15.2/maplibre-gl.css" rel="stylesheet"
13        integrity="sha384-DrPVD9GufrxGb7kWwRv0CywpXTmfvbKOZ5i5pN7urmIThew0zXKTME+gutUgtpeD" crossorigin="anonymous"
14        referrerpolicy="no-referrer">
15    </link>
16    <!-- Import Amplify  -->
17    <script src="https://cdn.amplify.aws/packages/core/5.0.5/aws-amplify-core.min.js" 
18        integrity="sha384-eM2urkpomL9SRm/kuPHZG3XPEItAiUAAyotT/AqlhSus8iAqs/EfHaYy1Jn5ih7K" crossorigin="anonymous"
19        referrerpolicy="no-referrer"></script>
20    <script src="https://cdn.amplify.aws/packages/auth/5.0.5/aws-amplify-auth.min.js"
21        integrity="sha384-H25CFLYd7YHa1Oib73fs3kJN36VhaHHkLjo4AhGrhJ4HuKam05pg2/0t2MR6epun" crossorigin="anonymous"
22        referrerpolicy="no-referrer"></script>
23    <script src="https://cdn.amplify.aws/packages/geo/2.0.5/aws-amplify-geo.min.js"
24        integrity="sha384-Esc9xx0X7ckb/yeYHuYsZGqBB4FwYr98NFHS3BRXLeRE/eB0uVrad2w+G6cGxYb5" crossorigin="anonymous"
25        referrerpolicy="no-referrer"></script>
26    <script src="https://cdn.amplify.aws/packages/maplibre-gl-js-amplify/1.5.0/maplibre-gl-js-amplify.umd.min.js"
27        integrity="sha384-9kJyZavd3Jk6QzHeaLpugVonfZmZZZdixek6uglOwzKtZvDS9K3W4dshw1uswmlV" crossorigin="anonymous"
28        referrerpolicy="no-referrer"></script>
29    </link>
30
31    <style>
32        body {
33            margin: 0;
34            padding: 0;
35        }
36
37        #map {
38            position: absolute;
39            top: 0;
40            bottom: 0;
41            width: 100%;
42        }
43    </style>
44</head>
45
46<body>
47    <div id="map"></div>
48    <script type="module">
49        import amplifyconfig from "./amplifyconfiguration.json" assert { type: "json" };
50        const { Amplify } = aws_amplify_core;
51        const { createMap } = AmplifyMapLibre;
52        Amplify.configure(amplifyconfig);
53
54        // Add code from below steps here
55    </script>
56</body>
57
58</html>

This code imports the MapLibre GL JS library and CSS, one of the popular options for map rendering we recommend for use with Amplify Geo. In the HTML body you create a <div> element with an id of 'map' that will be the map's container. Finally in the script section you'll setup some Amplify configuration that is required for Amplify Geo to understand what Amplify AWS resources have been created.

Setting up Amplify

You will need to use the Amplify CLI to setup Amplify Geo Map resources. Follow instructions for creating a map.
Once the CLI workflow has completed you should have an amplifyconfiguration.json file in the same directory as your index.html file.
Save your index.html file.

Display a map

In this step we will show you how to add code to display a map in your application.

With Amplify Geo and MapLibre you can add the following code to your index.html file inside the <script> tags, after the Amplify.configure command:

1const map = await createMap({
2  container: document.getElementById('map'), // div ID
3  center: [-122.4783, 37.8199], // initial coordinates [long, lat]
4  zoom: 13 // initial zoom level, high number being more zoomed in
5});

Save your HTML file and open it in a web browser to see your rendered map.

With the Google Maps JS API you can display a map like so.

1const map = new google.maps.Map(document.getElementById('map'), {
2  center: { lat: 37.8199, lng: -122.4783 },
3  zoom: 13
4});

Display a marker

Here you will add a marker to your map

With Amplify Geo and MapLibre you can do the following.

1const marker = new maplibregl.Marker().setLngLat([-122.4783, 37.8199]).addTo(map);

Save your changes and refresh your page and you should see a default blue marker icon on your map.

This example uses MapLibre's marker component to create a marker. To see more examples with markers on from MapLibre check the examples here.

Using the Google Maps JS API you would add a marker as show below.

1const marker = new google.maps.Marker({
2center: { lat: 37.8199, lng: -122.4783 },
3map: map
4});

A map with a marker

Now you can add a popup that displays information when a user clicks on a marker.

With Amplify Geo and MapLibre you can do the following.

1const popup = new maplibregl.Popup().setHTML(
2  `<h3>Golden Gate Bridge</h3><p>The hex code for the bridge's color is: #c0362c</p>`
3);
4
5const marker = new maplibregl.Marker()
6  .setLngLat([-122.4783, 37.8199])
7  .setPopup(popup)
8  .addTo(map);

Save your changes and refresh your page and now when you click on the icon a popup should appear on the screen.

This example uses MapLibre's popup component to create a marker popup. To see more examples with popups on from MapLibre check the examples here.

Using the Google Maps JS API you would add a marker as shown below.

1const marker = new google.maps.Marker({
2  center: { lat: 37.8199, lng: -122.4783 },
3  map: map
4});
5
6const infowindow = new google.maps.InfoWindow({
7  content: `<h3>Golden Gate Bridge</h3><p>The hex code for the bridge's color is: #c0362c</p>`
8});
9
10marker.addListener('click', () => {
11  infowindow.open(map, marker);
12});

A map with a marker popup

Add a search component

Now we can try adding a search bar to your map which can return results and place markers on a map based on those results.

With Amplify Geo and MapLibre you can do the following.

1const { createMap, createAmplifyGeocoder } = AmplifyMapLibre; // import from above updated to include createAmplifyGeocoder
2
3const geocoder = createAmplifyGeocoder();
4map.addControl(geocoder);

Save your changes and refresh your page and now when you should see a maplibre-gl-geocoder control in the top right corner of your map.

This example uses the MapLibre's geocoder component to create a search component. To see more options for our createAmplifyGeocoder utility function check out the docs here.

Using the Google Places JS API you would add a search bar as shown below.

1// Create the search box and link it to the UI element.
2const input = document.getElementById("pac-input") as HTMLInputElement;
3const searchBox = new google.maps.places.SearchBox(input);
4
5map.controls[google.maps.ControlPosition.TOP_LEFT].push(input);
6
7// Bias the SearchBox results towards current map's viewport.
8map.addListener("bounds_changed", () => {
9  searchBox.setBounds(map.getBounds() as google.maps.LatLngBounds);
10});
11
12// Listen for the event fired when the user selects a prediction and retrieve more details for that place.
13searchBox.addListener("places_changed", () => {
14  const places = searchBox.getPlaces();
15
16  if (places.length == 0) {
17    return;
18  }
19
20  // For each place, get the icon, name and location.
21  places.forEach((place) => {
22    // Create markers for each place
23    // Extend map view for each place
24  });
25  map.fitBounds(bounds);
26});

A search box

Add a stand alone search component

Now we can try adding a search bar without adding it to a map which can return results that you can use.

With Amplify Geo and MapLibre you can do the following.

1// Create a div to hold the search component
2const el = document.createElement("div");
3el.setAttribute("id", "search");
4document.body.appendChild(el);
5
6// Create the geocoder component and append it to the div you created earlier
7const geocoder = createAmplifyGeocoder();
8document.getElementById("search").appendChild(geocoder.onAdd());

Save your changes and refresh your page and now when you should see a maplibre-gl-geocoder control in the div you created.

This example uses the MapLibre's geocoder component to create a search component. To see more options for our createAmplifyGeocoder utility function check out the docs here.

Using the Google Places JS API you would add a stand alone search bar as shown below.

Some lines omitted for brevity, see the Google Maps Platform Places Search Box example for the full application

1// Create a input to hold the search component
2const el = document.createElement("input");
3el.setAttribute("id", "pac-input");
4document.body.appendChild(el);
5
6// Create the search box and link it to the UI element.
7const input = document.getElementById("pac-input");
8const searchBox = new google.maps.places.SearchBox(input);

Use existing Amazon Location resources

Use Amazon Location Service SDK