Forem: abraham poorazizi

How to choose the best geocoder for your project: a comparative analysis

abraham poorazizi — Thu, 04 May 2023 02:49:47 +0000

Geocoding is a fundamental process in many location-based applications, from mapping and navigation to marketing and logistics. It consists of three main steps: (1) parsing the input data (e.g., addresses), (2) querying the reference database, and (3) assigning geographic coordinates, which can be either obtained directly from the reference database or calculated using interpolation techniques. The primary outputs of the geocoding process are geographic coordinates (also known as longitude and latitude pairs). In addition to these, there are other byproducts such as address components that result from the address normalization process. This process converts an arbitrary address into a normalized address and its components, such as street number, street name, city, postal code, region, and country, which you can use for consistent address formatting and data enrichment.

Geocoding APIs provide a simple and efficient way for you to incorporate geocoding functionality into your applications, without having to create your own geocoding algorithms or reference databases. Amazon Location Service provides a geocoding API that offers two major benefits. Firstly, it provides a competitive pricing model that is up to 10 times cheaper than competitors, with the option to store and reuse geocoded data indefinitely. Secondly, it provides access to high-quality data from multiple data providers, giving you the flexibility to choose the provider with the best data quality for your project.

If you are wondering which data provider to use for your geocoding project, the answer depends on your area of interest. Each data provider may gather and curate their data using different techniques — for example they may use a combination of authoritative sources, open data, and AI-assisted mapping to compile their databases. Additionally, they may use different geocoding algorithms. Therefore, the quality of data sources and the accuracy of their methods have a direct effect on the quality of the output.

In this blog post, you will learn how to use quality metrics such as match rate, accuracy, and similarity to select the most suitable geocoder for your project. You can also use the evaluation framework presented here to compare different geocoders using your own data. By following these guidelines, you can make an informed decision on which geocoder to use, and ensure that your project has the necessary geocoding functionality to achieve its goals.

Evaluation framework

Amazon Location Service offers a geocoding API that sources data from multiple data providers including Esri, HERE, and GrabMaps, through its place index resource. In this blog post, you will create two place index resources using Esri and HERE as data providers and refer to them as "Esri geocoder" and "HERE geocoder". You will then evaluate their performance using the following quality metrics:

Match rate: it is the percentage of geocoded addresses divided by the total number of submitted addresses. A higher match rate indicates a higher likelihood of successful address resolution.
Accuracy: it compares the geocoding results to the baseline and consists of two metrics:
- Positional accuracy: it indicates how close each geocoded point is to the “true” location of the address, which is typically referred to as the baseline data or ground truth. It is determined by calculating the spatial distance between each geocoded point and the baseline. A shorter distance indicates higher positional accuracy of the geocoded points.
- Lexical accuracy: it indicates how close each returned address label is to the “true” address label (i.e., the baseline data or ground truth). It is determined by calculating a similarity score based on the Levenshtein distance between two strings (i.e., geocoded point vs. the baseline). The Levenshtein distance is a string metric that measures the minimum number of single-character edits (insertions, deletions or substitutions) required to transform one string into another. A higher score indicates higher lexical accuracy of the geocoded points.
Similarity: it performs a pairwise comparison between two different geocoders and consists of two metrics:
- Positional similarity: it indicates how similar two sets of geocoded points are in terms of their spatial positions. It is determined by calculating the pairwise distance between each point in the two sets. A shorter pairwise distance indicates a higher level of similarity between the two geocoders and a higher likelihood that they will produce equivalent geographic coordinates.
- Lexical similarity: it indicates how similar two sets of geocoded points are in terms of their format and spelling. It is measured by calculating pairwise similarity scores, using the Levenshtein distance, between pairs of geocoded points. A higher score indicates a higher level of similarity between the two geocoders and a higher likelihood that they will produce equivalent address labels.

The general process for comparing different geocoders involves the following steps:

Obtain a set of input addresses that need to be geocoded. Pick addresses that are relevant to your needs.
Obtain a set of corresponding baseline addresses, which represent the "true" location and label of the input addresses. This step may require manual cleaning and matching to ensure that each baseline address corresponds to the correct input address.
Geocode the input addresses using the geocoders that you want to evaluate.
Calculate the match rate to compare the overall effectiveness of different geocoders.
Calculate the accuracy metrics to compare how close the geocoding results are to the baseline.
Calculate the similarity metrics to measure the level of similarity between the two geocoders.
Analyze the results to determine which geocoder performs best based on your use case.

Evaluation scenarios

You will follow three test scenarios to compare the geocoders. You will use a set of 1,000 Canadian addresses, randomly selected (out of 562,000 residential addresses) from a dataset available on the City of Calgary’s open data portal, as the input to the geocoding process. Consider this dataset as the baseline for positional accuracy evaluation for all the scenarios. For each scenario, you will collect a set of corresponding Canada Post-verified addresses as the baseline to measure lexical accuracy. The test scenarios are:

Scenario 1: use the input data as is for this scenario. The input data is in CSV format with four fields: id, address, longitude, and latitude. The address field does not have information about the city, province, postal code, or country. The following shows the first five rows of the input data for the first scenario.

id,address,latitude,longitude
85,25 EVERGREEN CR SW,50.9215815275547,-114.100897916366
776,8608 METIS TR NE,51.1298266872992,-113.96923260807
916,121 SADDLEMEAD RD NE,51.1282839861152,-113.946243034372
1103,22 SADDLEBACK RD NE,51.1283490668448,-113.950394401587
1173,179 SADDLEMEAD RD NE,51.1288607473867,-113.944666215123

Scenario 2: enrich the original input data programmatically by appending city, province, and country to the address field. For example,25 EVERGREEN CR SW will be transformed into 25 EVERGREEN CR SW, Calgary, AB, Canada. You will use the enriched data as the input data for this scenario.
Scenario 3: In Calgary, the last part of the street name in an address indicates a city quadrant, such as SW for Southwest or NE for Northeast. For this scenario, use the input data from Scenario 2 and intentionally remove the "E" and "W" from the quadrant indicator to create misspelled addresses. For example, 25 EVERGREEN CR SW, Calgary, AB, Canada will be turned into 25 EVERGREEN CR S, Calgary, AB, Canada.

Walkthrough

Prerequisites

To complete this walkthrough, you will need access to an AWS account. Create an AWS account if you do not have one already. Next, create an IAM user with sufficient permissions to call the SearchPlaceIndexForText API. Then, create an access key ID and secret access key for Command Line Interface (CLI) access.

You will also need access to a Jupyter Notebook environment, with Python 3.9, for geocoding addresses and analyzing the results. You can use SageMaker Studio Lab, a free development environment to learn and experiment with data analysis and machine learning.

Additionally, you will need to download two datasets: (1) the residential address dataset (i.e., input data) and (2) the City of Calgary’s boundary dataset. After downloading the datasets, you will need to add the datasets to the project root directory of your Jupyter Notebook environment.

Finally, you will need access to Canada Post APIs to get Canada Post-verified addresses, which you will use as the baseline for lexical accuracy evaluations.

It is important to note that you need to pay for what you use when calling Amazon Location Service and Canada Post APIs. Visit Amazon Location Service pricing page and Canada Post pricing page to estimate the cost of this experiment.

Create Amazon Location resources

Head to the Amazon Location Service page in the AWS Management Console and create two Amazon Location Service’s place index resources called esri-geocoder and here-geocoder, with Esri and HERE as data providers (Figure 1).

Figure 1. Create two place index resources with Esri and HERE as data providers.

Geocode addresses

In this step, you will use Esri and HERE geocoders to geocode 1,000 residential addresses under three test scenarios. You will also collect a set of corresponding Canada Post-verified addresses as the baseline for lexical accuracy evaluation.

To start, open a new Terminal and create a .env file in your project root directory. Next, enter the AWS access key and secret access key that you created earlier, the AWS Region that you used to deploy the AWS resources, and your Canada Post API key.

AWS_ACCESS_KEY=YOUR_AWS_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY
AWS_REGION=YOUR_AWS_REGION
CANADA_POST_API_KEY=YOUR_CANADA_POST_API_KEY

Then, create a new Notebook and install the following dependencies:

! pip3 install boto3
! pip3 install python-dotenv
! pip3 install requests
! pip3 install pandas

boto3 is the AWS Python SDK that allows you to interact with AWS services. python-dotenv is a library that allows you to load environment variables from a .env file into your Notebook. requests is a Python library for making HTTP requests and handling responses in an easy and efficient way. pandas is a Python library for data manipulation and analysis that provides data structures for efficiently storing and working with large datasets.

Import the necessary libraries afterwards.

import boto3
import csv
from dotenv import load_dotenv
import os
import pandas as pd
import re
import requests

Next, load the environment variables and initialize a boto3 client to interact with Amazon Location Service’s geocoding API.

# Load environment variables from .env file
load_dotenv()

# Create a client for Amazon Location service
amazon_location_client = boto3.client(
    "location",
    aws_access_key_id=os.getenv("AWS_ACCESS_KEY"),
    aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    region_name=os.getenv("AWS_REGION"),
)

Then, create a function to call Esri and HERE geocoders, parse the API response, and return the input address ID, address components, and assigned geographic coordinates. Although geocoders usually return more than one (candidate) match for a given query to deal with ambiguity issues, configure them to return only one result per address for this experiment.

def amazon_location_geocoder(geocoder, address):
    # Search the Amazon Location Service place index for the given address text
    result = amazon_location_client.search_place_index_for_text(
        IndexName=geocoder, MaxResults=1, Text=address["text"]
    )

    # Extract geocoding results from the API response
    for result in result["Results"]:
        place = result["Place"]
        street_number = place.get("AddressNumber")
        street_name = place.get("Street")
        city = place.get("Municipality")
        province = place.get("Region")
        postal_code = place.get("PostalCode")
        country = place.get("Country")
        label = place.get("Label")
        geometry = place.get("Geometry")
        if geometry:
            longitude = geometry.get("Point", [None, None])[0]
            latitude = geometry.get("Point", [None, None])[1]
        else:
            longitude = None
            latitude = None

    # Return geocoding results in a standardized format
    return [
        {
            "id": address["id"],
            "street_number": street_number,
            "street_name": street_name,
            "city": city,
            "province": province,
            "postal_code": postal_code,
            "country": country,
            "label": label,
            "longitude": longitude,
            "latitude": latitude,
        }
    ]

Next, create a function to call the Canada Post APIs to get verified addresses. This function will first find addresses matching the input and return their IDs. It will then retrieve the full address details based on the IDs and return the input address IDs and address components. Note that Canada Post APIs do not return geographic coordinates.

def canada_post_geocoder(address):
    # Search the Canada Post API for the given address text
    url = f"https://ws1.postescanada-canadapost.ca/addresscomplete/interactive/find/v2.10/json.ws?key={os.getenv('CANADA_POST_API_KEY')}&provider=AddressComplete&package=Interactive&service=Find&version=2.1&endpoint=json.ws&SearchTerm={address['text']}&MaxSuggestions=1"
    response = requests.request("GET", url)
    data = response.json()
    id = data[0]["Id"]

    # Retrieve full geocoded address details from Canada Post API
    url = f"https://ws1.postescanada-canadapost.ca/addresscomplete/interactive/retrieve/v2.11/json.ws?key={os.getenv('CANADA_POST_API_KEY')}&provider=AddressComplete&package=Interactive&service=Retrieve&version=2.11&endpoint=json.ws&Id={id}"
    response = requests.request("GET", url)
    results = response.json()

    # Extract geocoding results from the API response
    for result in results:
        if "Language" in result and result["Language"] == "ENG":
            street_number = result.get("BuildingNumber")
            street_name = result.get("Street")
            city = result.get("City")
            province = result.get("ProvinceName")
            postal_code = result.get("PostalCode")
            country = result.get("CountryName")
            label = result.get("Label")

    # Return geocoding results in a standardized format
    return [
        {
            "id": address["id"],
            "street_number": street_number,
            "street_name": street_name,
            "city": city,
            "province": province,
            "postal_code": postal_code,
            "country": country,
            "label": label,
            "longitude": None,
            "latitude": None,
        }
    ]

Then, create a function to store the results in CSV format for analysis.

def save_csv(data, file_name):
    # Normalize JSON data into a flat table
    df = pd.json_normalize(data)
    # Save the data as a CSV file
    df.to_csv(file_name, encoding="utf-8", index=False)

Finally, run the three test scenarios against the geocoders and Canada Post APIs and store the results in CSV format. For Scenario 1, use the input data as-is.

# Scenario 1: address as is (incomplete)

with open("input/input-addresses.csv", newline="") as csvfile:
    amazon_location_esri_result = []
    amazon_location_here_result = []
    canada_post_result = []

    # Read CSV file and iterate over rows
    reader = csv.reader(csvfile, delimiter=",", quotechar="|")

    # Skip header row
    next(reader, None)
    for row in reader:
        print(row[0])

        # Create a dictionary containing the address information
        address = {"id": row[0], "text": f"{row[1]}"}

        try:
            # Call geocoding functions for Amazon Location Service with Esri and HERE providers,
            # and Canada Post
            amazon_location_esri_result.append(
                amazon_location_geocoder("esri-geocoder", address)
            )
            amazon_location_here_result.append(
                amazon_location_geocoder("here-geocoder", address)
            )
            canada_post_result.append(canada_post_geocoder(address))
        except Exception as e:
            print(e, row)

    # Save the geocoding results to CSV files
    save_csv(amazon_location_esri_result,
             "output/esri-geocoding-result-scenario-1.csv")
    save_csv(amazon_location_here_result,
             "output/here-geocoding-result-scenario-1.csv")
    save_csv(canada_post_result,
             "output/canada-post-geocoding-result-scenario-1.csv")

For Scenario 2, enrich the original input data programmatically by appending city, province, and country to the address field. Use the following code to configure the address and store the results in separate CSV files, for example esri-geocoding-result-scenario-2.csv.

...

    for row in reader:
        ...

        address = {"id": row[0], "text": f"{row[1]}, Calgary, AB, Canada"}

        ...

For Scenario 3, use the input data from Scenario 2 and intentionally remove the "E" and "W" from the quadrant indicator (i.e., the last part of the address) to create misspelled addresses. Use the following code to first define a regular expression pattern outside the loop, then configure the address and store the results in separate CSV files, for example esri-geocoding-result-scenario-3.csv.

with open("input/input-addresses.csv", newline="") as csvfile:
    ...

    # Define a regular expression pattern to match the letters "e" or "w", ignoring case
    pattern = re.compile("[ew]", re.IGNORECASE)

    ...

    for row in reader:
        ...

        # Split the address in the current row by whitespace
        address = row[1].split()
        # Retrieve the last item in the "address" list and remove any "e" or "w" characters found using the regular expression pattern
        address[-1] = re.sub(pattern, "", address[-1])
        # Rejoin the modified "address" list into a single string with whitespace in between each item
        misspelled_address = " ".join(address)

        address = {
            "id": row[0], "text": f"{misspelled_address}, Calgary, AB, Canada"}

        ...

The final output will consist of nine CSV files that contain the geocoding results across three test scenarios.

Analyze results

In this step, you will assess the performance of Esri and HERE geocoders across three test scenarios using match rate, and positional and lexical accuracy and similarity metrics. You will consider the residential property dataset from the City of Calgary as the baseline for positional accuracy evaluation and the geocoding results from Canada Post as the baseline for lexical accuracy evaluation.

To start, install the following dependencies:

! pip3 install pandas
! pip3 install geopandas
! pip3 install levenshtein

geopandas is a library that extends the functionality of pandas to include spatial data analysis and visualization capabilities. levenshtein is a string comparison library that provides functions to calculate the minimum edit distance and similarity scores between two strings. Minimum edit distance, also known as Levenshtein distance, is a measure of the difference between two sequences of characters, which is calculated by determining the minimum number of single-character edits (insertions, deletions, or substitutions) required to transform one sequence into the other.

Import the necessary libraries afterwards.

import pandas as pd
import geopandas as gpd
from Levenshtein import ratio

First, calculate the match rate for both geocoders across three test scenarios. The following code loads the geocoding results from Esri geocoder for Scenario 1 and calculates the match rate.

# Load data into a DataFrame
df = pd.read_csv("output/here-geocoding-result-scenario-1.csv")

# Add a new column to distinguish between matched and unmatched results
df["is_geocoded"] = df["longitude"].apply(
    lambda x: "yes" if not pd.isna(x) else "no")

# Calculate Match Rate
all_addresses_count = df.shape[0]
matched_addresses_count = df[df["is_geocoded"] == "yes"].shape[0]
match_rate = matched_addresses_count * 100 / all_addresses_count
print(f"match rate: {match_rate}%")

Next, conduct a point-in-polygon operation to calculate how many of the geocoded addresses fall inside the City of Calgary boundaries. Point-in-polygon operation is a spatial operation that determines if a point falls within a specific polygon such as a city or country boundary.

# Convert geocoded addresses into a GeoDataFrame and set the coordinate reference system to EPSG:4326
geocoded_addresses = df[df["is_geocoded"] == "yes"]
geocoded_addresses = gpd.GeoDataFrame(
    geocoded_addresses,
    geometry=gpd.points_from_xy(
        geocoded_addresses["longitude"], geocoded_addresses["latitude"]
    ),
).set_crs("epsg:4326")

# Load the city boundary dataset into a GeoDataFrame and set the coordinate reference system to EPSG:4326
city_boundary = gpd.read_file(
    "input/city-boundary.geojson").set_crs("epsg:4326")
#  Create a single geometry representing the entire city boundary
city_boundary = city_boundary["geometry"].unary_union

# Calculate the proportion of geocoded addresses that fall within the city boundaries
geocoded_addresses_within_city = geocoded_addresses[
    geocoded_addresses["geometry"].within(city_boundary)
]
proportion = round(len(geocoded_addresses_within_city)
                   * 100 / all_addresses_count, 1)
print(
    f"proportion of geocoded results that fall within city boundaries: {proportion}%")

For the next analysis, you will dive deeper into how much the geocoded results deviate from the baseline. First, calculate the spatial distance between each geocoded point and the baseline for both Esri and HERE geocoders across three test scenarios. The following code loads the baseline data and the geocoding results from Esri geocoder for Scenario 1, and calculates distances between each geocoded point and its corresponding baseline.

# Load data into DataFrames
baseline = pd.read_csv("input/input-addresses.csv")
geocoder = pd.read_csv("output/here-geocoding-result-scenario-1.csv")

# Convert DataFrames into GeoDataFrames with a local projection system (EPSG:3776 for Alberta) to calculate distances in meters
baseline = (
    gpd.GeoDataFrame(
        baseline,
        geometry=gpd.points_from_xy(
            baseline["longitude"], baseline["latitude"]),
    )
    .set_crs("epsg:4326")
    .to_crs("epsg:3776")
)
geocoder = (
    gpd.GeoDataFrame(
        geocoder,
        geometry=gpd.points_from_xy(
            geocoder["longitude"], geocoder["latitude"]),
    )
    .set_crs("epsg:4326")
    .to_crs("epsg:3776")
)

# Calculate the distance between the geocoded points and the baseline
baseline["distance"] = baseline["geometry"].distance(geocoder["geometry"])

# Calculate summary statistics
summary_stats = baseline["distance"].describe()
print(summary_stats)

Then, classify the distance values into five groups based distance thresholds (10m, 100m, 1km, 10km, and 10km+) to better understand their distribution.

# Classify distance values into 5 groups to better understand their distributions
labels = ["10m", "100m", "1km", "10km", "10km+"]
classes = [0, 10, 100, 1000, 10000, float("inf")]

baseline["distance_class"] = pd.cut(
    baseline["distance"], bins=classes, labels=labels, include_lowest=True
)

# Calculate summary statistics
counts = baseline["distance_class"].value_counts(sort=False)
print(counts)

summary_stats = baseline["distance_class"].describe()
print(summary_stats)

For the next analysis, evaluate the positional similarity of the geocoded results. The process is similar to the positional accuracy evaluation. However, instead of comparing geocoded results against a baseline, compare the results of the two geocoders. Similar to the positional accuracy analysis, classify the distance values into five groups to better understand their distribution.

Next, measure how similar returned address labels are to the baseline for both Esri and HERE geocoders across three test scenarios. Note that you can directly obtain labels from the label property returned by geocoders (i.e., provided labels) or construct them based on properties like street number, street name, city, province, postal code, and country using a consistent format (i.e., constructed labels). You will examine the impact of “provided” and “constructed” labels in this analysis.

First, calculate a similarity score for each geocoded point using provided labels. The following code loads the baseline data and the geocoding results from Esri geocoder for Scenario 1, and calculates a lexical accuracy score for each geocoded point.

# Load data into DataFrames
baseline = pd.read_csv("output/canada-post-geocoding-result-scenario-1.csv")
geocoder = pd.read_csv("output/esri-geocoding-result-scenario-1.csv")

# Rename the label column in all DataFrames and join them
baseline = baseline[["id", "label"]].rename(
    columns={"label": "label_baseline"})
geocoder = geocoder[["label"]].rename(columns={"label": "label_geocoder"})
df = pd.concat([baseline, geocoder], axis=1)

# Calculate lexical accuracy
df["lexical_accuracy"] = df.apply(
    lambda x: ratio(x["label_baseline"], x["label_geocoder"]), axis=1
)

# Calculate summary statistics
summary_stats = df["lexical_accuracy"].describe()
print(summary_stats)

Then, follow the same procedure as before and compute a similarity score for each record using constructed labels. The only difference here is that you will construct the label using address components. Use the following code to construct the labels.

# Construct labels and join DataFrames
baseline["label_baseline"] = baseline.apply(
    lambda x: f"{x['street_name']} {x['city']}, {x['province']}, {x['postal_code']}, {x['country']}",
    axis=1,
)
geocoder["label_geocoder"] = geocoder.apply(
    lambda x: f"{x['street_number']} {x['street_name']}, {x['city']}, {x['province']}, {x['postal_code']}, {x['country']}",
    axis=1,
)
df = pd.concat([baseline, geocoder], axis=1)

Finally, classify the scores into four groups (0.25, 0.5, 0.75, 1) to better understand their distribution.

# Classify distance values into 5 groups to better understand their distributions
labels = ["0.25", "0.5", "0.75", "1"]
classes = [0, 0.25, 0.5, 0.75, 1]

df["lexical_accuracy_class"] = pd.cut(
    df["lexical_accuracy"], bins=classes, labels=labels, include_lowest=True
)

# Calculate summary statistics
counts = df["lexical_accuracy_class"].value_counts(sort=False)
print(counts)

summary_stats = df["lexical_accuracy_class"].describe()
print(summary_stats)

For the final analysis, evaluate the lexical similarity of the geocoded results. The process is similar to the lexical accuracy evaluation, but instead of comparing geocoded results against a baseline, compare the results of the two geocoders. Like the lexical accuracy analysis, classify the similarity scores into four groups to better understand their distribution.

Evaluation

To evaluate the match rate, you geocoded the input addresses and performed a point-in-polygon test to determine if the returned geographic coordinates fell within the City of Calgary boundaries. In Scenario 1, the results indicate that HERE geocoder performed the best, achieving an overall match rate of 99.2%, with 84.1% of geocoded addresses falling inside the city boundaries (Table 1). In contrast, Esri geocoder had a match rate of 60.8%, with only 3.3% of the geocoded addresses falling within the city boundaries.

For Scenario 2 and Scenario 3, Esri geocoder achieved the highest match rate at 100%, marginally outperforming HERE geocoder by 2.5% and 3.3%, respectively.

		Esri	HERE
Scenario 1	Match rate	60.80%	99.20%
	Within city bounds	3.30%	84.10%
Scenario 2	Match rate	100%	97.50%
	Within city bounds	100%	97.40%
Scenario 3	Match rate	100%	96.70%
	Within city bounds	99.90%	96.40%

Table 1. Match rate of geocoded results.

For the positional accuracy test, you estimated the deviation of geocoding results from the baseline by calculating the spatial distance between each geocoded point and its corresponding baseline across three test scenarios. You then classified distance values into five groups to better understand their distribution.

In Scenario 1, the results (Table 2) suggest that HERE geocoder outperformed Esri geocoder with a median error distance of 18.49m (vs. 6,157km). The classification results (Figure 2) show that about 70% of geocoded points returned by HERE geocoder are within 100m of the baseline. However, geocoded results from Esri geocoder are mostly 10km away from the baseline.

For Scenario 2 and Scenario 3, the data suggests that Esri geocoder performed slightly better, with median error distances of 6.4m (vs. 16.79m) and 7.01m (vs. 17.01m), respectively. Half of the geocoded points by Esri geocoder fell between about 3m and 24m (vs. 13m and 75m) for Scenario 2 and between about 3m and 41m (vs. 14m and 94m) for Scenario 3. The classification results (Figure 2) show that about 60% of geocoded points returned by Esri geocoder are within 10m of the baseline, while more than 65% of geocoded points returned by HERE geocoder are within 100m of the baseline.

	Scenario 1		Scenario 2		Scenario 3
	Esri	HERE	Esri	HERE	Esri	HERE
Min (m)	0.53	0.47	0	0.47	0	0.47
Max (m)	22,575,139.36	22,517,070.99	1,519.57	45,140.98	180,513.23	52,277.26
Median (m)	6,156,974.76	18.49	6.4	16.79	7.01	17.01
IQR (Q3-Q1) (m)	15,847,869.85	238.73	21.33	61.62	37.72	80.55
Mean (m)	7,976,346.72	516,877.99	58.26	248.63	351.37	511.25
Standard deviation (m)	6,880,389.06	1,772,337.79	168.38	1,726.07	5,791.3	3,015.81

Table 2. The descriptive statistics of positional accuracy for Esri and HERE geocoders.

Figure 2. The distribution of error distances computed between each geocoded point and its corresponding baseline for each geocoder across three test scenarios.

For the next analysis, you evaluated the positional similarity between the geocoders using relative distances. You then classified distance values into five groups to better understand their distribution.

The results indicate that although the two geocoders performed differently in Scenario 1, with a median pairwise distance of 6,608km, they showed strong similarities in Scenario 2 and Scenario 3, with a median pairwise distance of 12m and 13m, respectively (Table 3). In Scenario 1, the data shows a great variation of pairwise distances between geocoded points, with 94% of the points being more than 10km apart (Figure 3). However, for more than 70% of the geocoded results in the second and third scenarios, the two geocoders generated points within a 100m distance, with over 30% of those points being closer than 10m.

	Scenario 1	Scenario 2	Scenario 3
Min (m)	0	0.03	0.03
Max (m)	27,023,925.72	45,146.2	173,911.89
Median (m)	6,608,269.48	12.03	13.04
IQR (Q3-Q1) (m)	16,208,528.66	38.77	107.46
Mean (m)	8,003,303.66	241.14	765.18
Standard deviation (m)	7,079,866.15	1,727.7	6,389.32

Table 3. The descriptive statistics of positional similarity between Esri and HERE geocoders across three test scenarios.

Figure 3. The distribution of distances between paired geocoded points returned by Esri and HERE geocoders across three test scenarios.

For lexical accuracy evaluation, you measured the similarity between the provided and constructed address labels and the baseline by calculating a score between 0 and 1. You then classified the scores into four groups to better understand their distribution.

The results suggest that HERE geocoder produced the most similar address labels to the baseline in Scenario 1, with median scores of 0.60 (vs. 0.0) and 0.80 (vs. 0.36) when using provided and constructed labels, respectively (Table 4). Figure 4 shows that for provided labels (i.e., the address labels returned by geocoders), the majority of the geocoded results (~ 60%) returned by Esri and HERE geocoders achieved a score of 0.25 and 0.75, respectively. However, using constructed labels (i.e., the address labels created based on individual address components) significantly improved the scores, with the scores going up to 0.5 and 1 for Esri and HERE geocoders, respectively (Figure 5).

In Scenario 2 and Scenario 3, both geocoders performed similarly, with over 70% of the geocoded results achieving a lexical accuracy score of 0.75 or higher. It is also evident that both geocoders performed significantly better when using constructed labels.

		Scenario 1		Scenario 2		Scenario 3
		Esri	HERE	Esri	HERE	Esri	HERE
Min	Provided labels	0	0	0	0	0	0
	Constructed labels	0.19	0.21	0.24	0.26	0.25	0.22
Max	Provided labels	0.79	0.73	0.79	0.73	0.79	0.73
	Constructed labels	0.9	0.9	0.91	0.91	0.91	0.9
Median	Provided labels	0	0.6	0.71	0.64	0.67	0.64
	Constructed labels	0.36	0.8	0.87	0.85	0.86	0.85
IQR (Q3-Q1) (m)	Provided labels	0.36	0.39	0.14	0.13	0.07	0.21
	Constructed labels	0.09	0.49	0.09	0.09	0.12	0.15
Mean	Provided labels	0.17	0.45	0.65	0.58	0.62	0.55
	Constructed labels	0.42	0.65	0.82	0.8	0.79	0.77
Standard deviation	Provided labels	0.2	0.27	0.16	0.17	0.18	0.2
	Constructed labels	0.17	0.25	0.12	0.14	0.15	0.16

Table 4. The descriptive statistics of lexical accuracy for Esri and HERE geocoders across three test scenarios.

Figure 4. The distribution of lexical accuracy scores calculated using provided labels across three test scenarios.

Figure 5. The distribution of lexical accuracy scores calculated using constructed labels across three test scenarios.

Finally, you evaluated the lexical similarity between the geocoders by calculating pairwise similarity scores between pairs of geocoded points. You then classified the scores into four groups to better understand their distribution.

The results indicate that the two geocoders performed differently in Scenario 1, regardless of the type of label used in the experiment (Table 5). However, they showed strong similarities in the next two scenarios, with median pairwise scores above 0.86 (Figure 6). It is also evident that both geocoders produced equivalent results when using constructed labels, achieving median similarity scores of 1.00 and 0.99 in Scenario 2 and Scenario 3, respectively.

		Scenario 1	Scenario 2	Scenario 3
Min	Provided labels	0	0	0
	Constructed labels	0.22	0.28	0.28
Max	Provided labels	0.93	0.93	0.93
	Constructed labels	1	1	1
Median	Provided labels	0.33	0.9	0.86
	Constructed labels	0.37	1	0.99
IQR (Q3-Q1)	Provided labels	0.45	0.1	0.11
	Constructed labels	0.19	0.05	0.1
Mean	Provided labels	0.26	0.84	0.81
	Constructed labels	0.42	0.96	0.93
Standard deviation	Provided labels	0.24	0.15	0.17
	Constructed labels	0.14	0.11	0.13

Table 5. The descriptive statistics of lexical similarity for Esri and HERE geocoders across three test scenarios.

Figure 6. The distribution of lexical similarity scores calculated using provided labels across three test scenarios.

Figure 7. The distribution of lexical similarity scores calculated using constructed labels across three test scenarios.

Next steps

When considering geocoding for your own project, it is important to evaluate the performance of geocoders using representative data specific to your use case. While a general evaluation can offer an idea of how various geocoders perform, it may not accurately reflect their performance on your own data. Your data may have unique characteristics, such as specific address formats or geographic coverage, that can influence the performance of geocoders. By evaluating geocoders with your own data, you can gain a better understanding of the strengths and limitations of different geocoding methods, and make an informed decision on which geocoder to use in your project.

You can explore the associated GitHub repository for this project, download the code, and configure it to run this experiment with your own data. By delving into the code and conducting your own experiment, you can gain a more comprehensive understanding of the methodology and determine which geocoding approach and quality metrics are best suited for your specific use case.

Conclusion

Amazon Location Service provides a geocoding API that sources data from different data providers, including Esri and HERE. This gives you the flexibility to choose a provider with the best quality data for your project. However, it is important to note that data quality may vary based on your area of interest, as data providers may use different geocoding algorithms, data sources, and update cycles. In this blog post, you learned how to select the right data provider for your geocoding project using metrics like match rate, accuracy, and similarity. You can use the evaluation framework presented in this blog post to choose the right data provider and geocoding API for various use cases or geographies.

Build interactive maps with OpenStreetMap data on AWS

abraham poorazizi — Thu, 29 Dec 2022 00:22:18 +0000

OpenStreetMap (OSM) is a free, editable map of the world. Over 1.8 million map makers have contributed to OSM since 2004, updating more than 500,000 features daily. AWS has recently announced the public preview of Open Data Maps for Amazon Location Service. This means that you can now access global base maps built from OSM and other open data sources like Natural Earth to add interactive maps to web and mobile applications.

OSM data is free and the open-source community has created an amazing toolchain to work with it, from storage to processing and rendering — visit Swith2OSM to learn more about the OSM ecosystem. You can also run your own "map stack" on AWS. In fact, you can follow the Serverless Vector Tiles on AWS tutorial to build and deploy your own map tiles using Amazon S3, Amazon Route 53, AWS Certificate Manager, and Amazon CloudFront. However, it may become a challenge to maintain your solution over time in a scalable way, especially when you deal with an OSM extract for a large area. As a result, you may delay or not refresh the data at all, resulting in degradation of location data quality over time and negatively impacting the end-user experience.

To address those challenges, you can use Open Data Maps from Amazon Location Service, a fully-managed location-based service from AWS. Amazon Location Service regularly refreshes its OSM data with thorough quality and consistency checks, enabling you to build applications with up-to-date location information. You can rely on the security, reliability, and performance of Amazon Location Service to build geospatial solutions at scale.

In this post, you will learn how to build an interactive map with the new Open Data Maps option from Amazon Location Service. Create an AWS account, if you don’t have one already, and let’s dive right in.

Create AWS resources

You will use an AWS CloudFormation template to create a number of AWS resources, including an Amazon Location Service’s map resource, an Amazon Cognito Identity Pool, plus an IAM role and policy. The Identity Pool, and IAM role and policy are necessary to grant access to the map resource. This way a frontend application can send signed HTTP requests to Amazon Cognito and receive temporary, scoped-down credentials that are valid for an hour. Then, it can use those credentials to request map tiles from Amazon Location Service’s Maps API and render them in the browser.

For this project, you will allow for unauthenticated guest access to your application — see Granting access to Amazon Location Service to explore more options. Click this link to deploy this CloudFormation template into your AWS account. It will open the AWS Management Console and initiate the deployment process. Check the I acknowledge that AWS CloudFormation might create IAM resources box; then select the Create stack button.

Once the deployment process is complete, go to the Outputs section to get the Identity Pool ID.

Build a web map

Create an empty HTML file, index.html, and add the following content to it.

<html>
  <head>
    <link
      href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css"
      rel="stylesheet"
    />
    <style>
      body {
        margin: 0;
        padding: 0;
      }
      #map {
        position: absolute;
        top: 0;
        bottom: 0;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
    <script src="https://unpkg.com/amazon-location-helpers@1.1"></script>
    <script>
      async function initializeApp() {
        const map = await AmazonLocation.createMap(
          {
            identityPoolId: "YOUR_COGNITO_IDENTITY_POOL",
          },
          {
            container: "map",
            center: [-114.07, 51.0553],
            zoom: 16,
            style: "OpenDataMap",
          }
        );

        map.addControl(new maplibregl.NavigationControl(), "top-right");

        const popup = new maplibregl.Popup({ offset: 35 }).setHTML(
          `<h3>Prince's Island Park</h3>
           <img width="200" src="https://upload.wikimedia.org/wikipedia/commons/thumb/0/02/Calgary1-Szmurlo.jpg/320px-Calgary1-Szmurlo.jpg" />`
        );

        const marker = new maplibregl.Marker()
          .setLngLat([-114.07, 51.0553])
          .setPopup(popup)
          .addTo(map);
      }

      initializeApp();
    </script>
  </body>
</html>

Enter your Cognito Identity Pool ID and save the changes. Now, if you open the HTML file in your browser, you will see an interactive map with navigation controls and a marker with popup information.

Clean up

If you would like to remove the AWS resources created in this project, delete the CloudFormation stack called open-data-maps-demo.

Wrap up

AWS has recently added Open Data as a new data provider for Amazon Location Service. This allows you to use global base maps, built from OSM and other open data sources, to build geospatial web and mobile applications. In this post, you learned how to use Amazon Location Service’s Maps API to build a simple web map using OSM data. The source code for this project is available on GitHub. I’d love to hear your feedback, so please reach out to me if you have any questions and comments, or ideas on what I should build and write about next.

How to build an online route planner with Amazon Location Service

abraham poorazizi — Wed, 14 Sep 2022 05:59:18 +0000

Route finding is something that many of us use almost everyday to go from one place to another. Depending on our daily routines, personal preferences, or occupation, we may rely on different modes of transportation, choose different times of day, or consider some restrictions (or avoidances) to get to our destination(s). We usually use an app for this purpose and there are many of them out there. In this post, you will learn how to build one yourself on AWS in seven steps.

We will build a Vue app using Amazon Location Service, as the basemap provider and routing API, MapLibre GL JS, as the map rendering library, and Naive UI, as the UI component library. The app will have a map with navigation controls and a route calculator that finds the fastest route using a number of parameters such as different modes of transportation (car, truck, and walking), departure time, avoidances (ferries and tolls), and weight and size limitations for trucks — the following screenshot shows the end results.

Prerequisites

We will create the AWS resources for this project using AWS CLI. Before we start

Create an AWS account, if you do not have one already.
Install and configure AWS CLI on your machine.

1. Create a map resource

Amazon Location Service’s Maps API offers a set of map styles, professionally designed to support different applications and use cases — see Esri map styles and HERE map styles for more details. Now, create a map resource using the map style Esri Navigation.

aws location create-map \
--map-name=esri-map-navigation \
--configuration Style=VectorEsriNavigation \
--profile={YOUR_AWS_PROFILE}

Once a new map resource is created, you will see an output that contains the map resource’s creation time, ARN, and name.

{
    "CreateTime": "2022-09-03T21:00:41.391000+00:00",
    "MapArn": "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT}:map/esri-map-navigation",
    "MapName": "esri-map-navigation"
}

2. Create a route calculator resource

Amazon Location Service’s Routes API provides a route calculator resource that finds optimal routes based on up-to-date road networks and traffic information from two global data providers, Esri and HERE. Let’s create a route calculator resource, with Esri as our data provider.

aws location create-route-calculator \
--calculator-name "esri-route-calculator" \
--data-source "Esri" \
--profile={YOUR_AWS_PROFILE}

Once a new route calculator resource is created, you will see an output that contains the route calculator resource’s creation time, ARN, and name.

{
    "CreateTime": "2022-09-03T21:25:36.297000+00:00",
    "CalculatorArn": "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT}:route-calculator/esri-route-calculator",
    "CalculatorName": "esri-route-calculator"
}

3. Grant access to Amazon Location resources

Now, you need to grant access to the resources that you have created so far by creating an Amazon Cognito identity pool and an IAM policy. This way a frontend application can send signed HTTP requests to Amazon Cognito and receive temporary, scoped-down credentials that are valid for an hour. Then, it can use those credentials to request map tiles and optimal routes from Amazon Location Service’s Maps and Routes APIs.

For this project, we will allow for unauthenticated guest access to our application — see Granting access to Amazon Location Service to explore more options. First, create an Amazon Cognito identity pool.

aws cognito-identity create-identity-pool \
--identity-pool-name routing-app \
--allow-unauthenticated-identities \
--profile={YOUR_AWS_PROFILE}

Once a new identity pool is created, you will see an output that contains the identity pool ID, name, and a confirmation for allowing unauthenticated access.

{
    "IdentityPoolId": "{IDENTITY_POOL_ID}",
    "IdentityPoolName": "routing-app",
    "AllowUnauthenticatedIdentities": true,
    "IdentityPoolTags": {}
}

Next, create a new IAM role that you want to use with your identity pool. Note that you must provide a policy document, as an input parameter, to establish trust between Amazon Cognito and AWS Security Token Service (STS). This will allow your identity pool to request temporary tokens from STS. Here is an example of a policy document in JSON — make sure to convert it to string before using it with the CLI command.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "Federated":"cognito-identity.amazonaws.com"
         },
         "Action":"sts:AssumeRoleWithWebIdentity",
         "Condition":{
            "StringEquals":{
               "cognito-identity.amazonaws.com:aud":"{IDENTITY_POOL_ID}"
            },
            "ForAnyValue:StringLike":{
               "cognito-identity.amazonaws.com:amr":"unauthenticated"
            }
         }
      }
   ]
}

Now, let’s create a new IAM role.

aws iam create-role \
--role-name Cognito_routing_app_Unauth_Role \
--assume-role-policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Federated\":\"cognito-identity.amazonaws.com\"},\"Action\":\"sts:AssumeRoleWithWebIdentity\",\"Condition\":{\"StringEquals\":{\"cognito-identity.amazonaws.com:aud\":\"{IDENTITY_POOL_ID}\"},\"ForAnyValue:StringLike\":{\"cognito-identity.amazonaws.com:amr\":\"unauthenticated\"}}}]}" \
--profile={YOUR_AWS_PROFILE}

Once a new IAM role is created, you will see an output that contains some metadata about the role including the role name and the policy document you provided in the request.

{
    "Role": {
        "Path": "/",
        "RoleName": "Cognito_routing_app_Unauth_Role",
        "RoleId": "AROA3K4ALINNDDUQ3Q2XB",
        "Arn": "arn:aws:iam::{AWS_ACCOUNT}:role/Cognito_routing_app_Unauth_Role",
        "CreateDate": "2022-09-03T22:19:56+00:00",
        "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {
                        "Federated": "cognito-identity.amazonaws.com"
                    },
                    "Action": "sts:AssumeRoleWithWebIdentity",
                    "Condition": {
                        "StringEquals": {
                            "cognito-identity.amazonaws.com:aud": "{IDENTITY_POOL_ID}"
                        },
                        "ForAnyValue:StringLike": {
                            "cognito-identity.amazonaws.com:amr": "unauthenticated"
                        }
                    }
                }
            ]
        }
    }
}

Then, attach an inline policy document to the IAM role that you have just created. The policy will grant access to your map and route calculator resources. Here is an example of a policy document in JSON — make sure to convert it to string before using it with the CLI command.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Sid":"MapsRoutesReadOnly",
         "Effect":"Allow",
         "Action":[
            "geo:GetMap*",
            "geo:CalculateRoute"
         ],
         "Resource":[
            "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT}:map/esri-map-navigation",
            "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT}:route-calculator/esri-route-calculator"
         ]
      }
   ]
}

Now, let’s attach the policy to the IAM role.

aws iam put-role-policy \
--role-name Cognito_routing_app_Unauth_Role \
--policy-name Cognito_routing_app_Unauth_Role_Policy \
--policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"MapsRoutesReadOnly\",\"Effect\":\"Allow\",\"Action\":[\"geo:GetMap*\",\"geo:CalculateRoute\"],\"Resource\":[\"arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT}:map/esri-map-navigation\",\"arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT}:route-calculator/esri-route-calculator\"]}]}" \
--profile={YOUR_AWS_PROFILE}

Finally, add the IAM role to your identity pool.

aws cognito-identity set-identity-pool-roles \
--identity-pool-id "{IDENTITY_POOL_ID}" \
--roles unauthenticated="arn:aws:iam::{AWS_ACCOUNT}:role/Cognito_routing_app_Unauth_Role" \
--profile={YOUR_AWS_PROFILE}

4. Set up a new project

Create a new Vue project using Vite.

npm create vite@latest

Choose a name for your project and pick vue as the framework and variant.

✔ Select a variant: › vue
✔ Project name: amazon-location-route-planner
✔ Select a framework: › vue

Next, go into your project’s root directory and install the dependencies.

cd amazon-location-route-planner
npm install

Then, replace the content of App.vue with the following code.

<template>
</template>

<script setup>
</script>

<style>
</style>

Finally, add the following configuration to vite.config.

export default defineConfig({
  ...

  define: {
    global: {}
  }
});

5. Add auth configurations

First, install a few dependencies.

npm install @aws-amplify/core @aws-sdk/client-cognito-identity @aws-sdk/credential-provider-cognito-identity

Next, create a new file, config.js, under src directory and enter your Cognito identity pool ID.

const identityPoolId = "{IDENTITY_POOL_ID}";

export { identityPoolId };

Then, create a new file, auth.js, under src directory and add the following code to the new file. This will provide a few variables and functions that we will use later on to communicate with Amazon Location Service’s APIs:

region which indicates your AWS region
credentials, which are the credentials obtained from Amazon Cognito
refreshCredentials, which is a function that automatically renews credentials before they expire
transformRequest, which is a function that signs HTTP request sent to the Amazon Location Service’s Maps API using AWS SigV4 with the credentials obtained from Amazon Cognito

import { Signer } from "@aws-amplify/core";
import { fromCognitoIdentityPool } from "@aws-sdk/credential-provider-cognito-identity";
import { CognitoIdentityClient } from "@aws-sdk/client-cognito-identity";
import { identityPoolId } from "./config";

const region = identityPoolId.split(":")[0];

const identityProvider = fromCognitoIdentityPool({
  client: new CognitoIdentityClient({
    region: region,
  }),
  identityPoolId,
});

let credentials;
const refreshCredentials = async () => {
  credentials = await identityProvider();
  setTimeout(refreshCredentials, credentials.expiration - new Date());
};

const transformRequest = (url, resourceType) => {
  if (resourceType === "Style" && !url.includes("://")) {
    url = `https://maps.geo.${region}.amazonaws.com/maps/v0/maps/${url}/style-descriptor`;
  }

  if (url.includes("amazonaws.com")) {
    return {
      url: Signer.signUrl(url, {
        access_key: credentials.accessKeyId,
        secret_key: credentials.secretAccessKey,
        session_token: credentials.sessionToken,
      }),
    };
  }

  return { url };
};

export { region, credentials, refreshCredentials, transformRequest };

6. Add a map

First, install maplibre-gl, our map rendering library.

npm install maplibre-gl

Next, open src/config.js and add the name of your map resource.

...

const mapName = "esri-map-navigation";

export { identityPoolId, mapName };

Then, open App.vue and add a div container for the map.

<template>
   <div id="map"></div>
</template>

Afterwards, add a new map instance with navigation controls.

<script setup>
import maplibregl from "maplibre-gl";
import { refreshCredentials, transformRequest } from "./auth";
import { mapName } from "./config";

let map = null;

const initializeApp = async () => {
  await refreshCredentials();

  map = new maplibregl.Map({
    container: "map",
    center: [-114.067375, 51.046333],
    zoom: 16,
    style: mapName,
    hash: true,
    transformRequest,
  });

  map.addControl(new maplibregl.NavigationControl(), "bottom-right");
}

initializeApp();
</script>

Finally, add the following CSS to produce a full screen map.

<style>
@import "maplibre-gl/dist/maplibre-gl.css";

body {
  margin: 0;
  padding: 0;
}
#map {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 0;
  width: 100%;
}
</style>

Now, if you run npm run dev in your terminal and go to your browser, you will see an interactive map on the page.

7. Add a route calculator

An Amazon Location Service’s route calculator resource provides an operation called CalculateRoute that finds optimal routes between an origin, a destination, and up to 23 stops along the way (or waypoints) for different modes of transportation, avoidances, and departure times — check out the API docs to see all the supported parameters.

For this project, we will build a route calculator widget that supports the following parameters:

DeparturePosition — It specifies the starting point as [longitude, latitude].
DestinationPosition — It specifies the destination as [longitude, latitude].
WaypointPositions — It specifies an ordered list of up to 23 intermediate positions to include along a route between the departure and destination positions as [[longitude, latitude], [longitude, latitude]].
TravelMode — It specifies the mode of transportation when calculating a route, including Car, Truck, or Walking.
DistanceUnit — It specifies the unit of measurement for travel distance, including Kilometers or Miles.
CarModeOptions — It specifies route preferences when traveling by Car, including avoiding routes that use ferries , AvoidFerries, and tolls, AvoidTolls.
TruckModeOptions — It specifies route preferences when traveling by Truck, including avoiding routes that use ferries, AvoidFerries, and tolls, AvoidTolls. It also specifies the weight, Weight, and size, including Height, Length, and Width, of the truck to avoid routes that will not accommodate it.
DepartNow — It sets the time of departure as the current time.
DepartureTime — It specifies the desired time of departure.

The calculated route will include the overall travel time and distance, unit of measurement, and route geometry, among other things — check out the API docs to see the API response elements.

Now, let’s start with installing a few dependencies.

npm install @aws-sdk/client-location @turf/helpers

npm install -D naive-ui vfonts @vicons/carbon

Next, open src/config.js and add the name of your route calculator resource.

...

const routeCalculatorName = "esri-route-calculator";

export { identityPoolId, mapName, routeCalculatorName };

Afterwards, open App.vue and add a card with seven sections for (1) transportation mode, (2) route summary, (3) starting point, waypoints, and destination, (4) unit of measurement options, (5) avoid options, (6) departure time options, and (7) truck options. Note that the last three sections are only for cars and trucks.

<template>
  ...

  <n-card>
    <n-space vertical>

      <!-- Travel mode options -->
      <n-radio-group v-model:value="travelModeOptions">
        <n-radio-button value="Car"> Car </n-radio-button>
        <n-radio-button value="Truck"> Truck </n-radio-button>
        <n-radio-button value="Walking"> Walking </n-radio-button>
      </n-radio-group>

      <n-space style="margin: 20px 0 20px 0">
        Click on the map to choose your starting point and destination(s).
      </n-space>

      <!-- Route summary -->
      <n-h3 v-if="route.features.length > 0">
        <n-text type="primary">
          {{ Math.round(route.features[0].properties.DurationSeconds / 60) }}
          Minutes
        </n-text>
        <n-text depth="3">
          ({{ route.features[0].properties.Distance.toFixed(1) }}
          {{ route.features[0].properties.DistanceUnit }})
        </n-text>
      </n-h3>

      <!-- Starting point and destinations -->
      <n-space>
        <n-timeline>
          <n-timeline-item
            v-for="position in positions.features"
            type="info"
            :content="position.geometry.coordinates.join(', ')"
            :title="position.properties.title"
            line-type="dashed"
          />
        </n-timeline>
      </n-space>
    </n-space>
    <n-collapse style="margin-top: 20px">

      <!-- Unit of measurement options -->
      <n-collapse-item title="Unit of measurement" name="1">
        <n-radio-group v-model:value="unitOfMeasurementOptions">
          <div>
            <n-radio value="metric"> Metric </n-radio>
          </div>
          <div>
            <n-radio value="imperial"> Imperial </n-radio>
          </div>
        </n-radio-group>
        <template #header-extra>
          <n-icon :component="RulerAlt" />
        </template>
      </n-collapse-item>

      <!-- Avoid options -->
      <n-collapse-item
        v-if="travelModeOptions === 'Car' || travelModeOptions === 'Truck'"
        title="Avoid options"
        name="2"
      >
        <n-checkbox-group v-model:value="avoidOptions">
          <div>
            <n-checkbox value="AvoidTolls" label="Tolls" />
          </div>
          <div>
            <n-checkbox value="AvoidFerries" label="Ferries" />
          </div>
        </n-checkbox-group>
        <template #header-extra>
          <n-icon :component="DirectionFork" />
        </template>
      </n-collapse-item>

      <!-- Truck options -->
      <n-collapse-item
        v-if="travelModeOptions === 'Truck'"
        title="Truck options"
        name="3"
      >
        <n-input
          clearable
          :placeholder="`Height (${units[unitOfMeasurementOptions]['truck']['dimension']})`"
          v-model:value="truckHeight"
        >
          <template #prefix>
            <n-icon :component="FitToHeight" />
          </template>
        </n-input>
        <n-input
          clearable
          :placeholder="`Width (${units[unitOfMeasurementOptions]['truck']['dimension']})`"
          v-model:value="truckWidth"
          style="margin-top: 10px"
        >
          <template #prefix>
            <n-icon :component="CenterToFit" />
          </template>
        </n-input>
        <n-input
          clearable
          :placeholder="`Length (${units[unitOfMeasurementOptions]['truck']['dimension']})`"
          v-model:value="truckLength"
          style="margin-top: 10px"
        >
          <template #prefix>
            <n-icon :component="FitToWidth" />
          </template>
        </n-input>
        <n-input
          clearable
          :placeholder="`Weight (${units[unitOfMeasurementOptions]['truck']['weight']})`"
          v-model:value="truckWeight"
          style="margin-top: 10px"
        >
          <template #prefix>
            <n-icon :component="Scales" />
          </template>
        </n-input>
        <template #header-extra>
          <n-icon :component="DeliveryTruck" />
        </template>
      </n-collapse-item>

      <!-- Departure time options -->
      <n-collapse-item
        v-if="travelModeOptions === 'Car' || travelModeOptions === 'Truck'"
        title="Departure time"
        name="4"
      >
        <n-radio-group v-model:value="departureTimeOptions">
          <div>
            <n-radio value="default"> Optimal traffic conditions </n-radio>
          </div>
          <div>
            <n-radio value="now"> Now </n-radio>
          </div>
          <div>
            <n-radio value="custom"> Leave at </n-radio>
          </div>
        </n-radio-group>
        <n-input-group
          v-if="departureTimeOptions === 'custom'"
          style="margin-top: 15px"
        >
          <n-date-picker v-model:value="timestamp" type="datetime" clearable />
        </n-input-group>
        <template #header-extra> <n-icon :component="Time" /> </template>
      </n-collapse-item>
    </n-collapse>
  </n-card>
</template>

Next, import the required configurations, functions, and components into App.vue.

<script setup>
...

mport { ref, watch, computed, reactive } from "vue";
import {
  LocationClient,
  CalculateRouteCommand,
} from "@aws-sdk/client-location";
import {
  NCard,
  NRadioGroup,
  NRadioButton,
  NRadio,
  NCheckboxGroup,
  NCheckbox,
  NInput,
  NInputGroup,
  NDatePicker,
  NIcon,
  NSpace,
  NCollapse,
  NCollapseItem,
  NTimeline,
  NTimelineItem,
  NH3,
  NText,
} from "naive-ui";
import {
  RulerAlt,
  DirectionFork,
  Time,
  DeliveryTruck,
  FitToHeight,
  FitToWidth,
  CenterToFit,
  Scales,
} from "@vicons/carbon";
import { point, lineString, featureCollection } from "@turf/helpers";
import {
  region,
  credentials,
  refreshCredentials,
  transformRequest,
} from "./auth";
import { mapName, routeCalculatorName } from "./config";

...
</script>

Then, define the required variables to capture the transportation mode, positions (departure, waypoints, and destination), calculated route, unit of measurement, avoid option, departure time option, and the weight and size of trucks.

<script setup>
...

let travelModeOptions = ref("Car");
const positions = reactive(featureCollection([]));
const route = reactive(featureCollection([]));

let unitOfMeasurementOptions = ref("metric");
const units = {
  metric: {
    route: { distance: "Kilometers" },
    truck: { dimension: "Meters", weight: "Kilograms" },
  },
  imperial: {
    route: { distance: "Miles" },
    truck: { dimension: "Feet", weight: "Pounds" },
  },
};

const avoidOptions = ref([]);
let departureTimeOptions = ref("default");
let timestamp = ref(Date.now());

let truckHeight = ref(null);
let truckWidth = ref(null);
let truckLength = ref(null);
let truckWeight = ref(null);

...
</script>

Afterwards, add an event handler to capture clicks on the map and store them in positions as GeoJSON.

<script setup>
...

const initializeApp = async () => {
  ...

  let counter = 0;
  map.on("click", async (e) => {
    counter++;
    const { lngLat } = e;
    const p = point([lngLat.lng.toFixed(5), lngLat.lat.toFixed(5)], {
      title: `Point ${counter}`,
    });
    positions.features.push(p);
  });
}

...
</script>

Next, add a computed property to build the request body for the API call.

<script setup>
...

const requestParams = computed(() => {
  const params = {
    CalculatorName: routeCalculatorName,
    TravelMode: travelModeOptions.value,
    DistanceUnit: units[unitOfMeasurementOptions.value]["route"]["distance"],
    IncludeLegGeometry: true,
  };

  // Positions (DeparturePosition, WaypointPositions, and DestinationPosition)
  if (positions.features.length > 1) {
    params.DeparturePosition = positions.features[0].geometry.coordinates;

    params.DestinationPosition =
      positions.features[positions.features.length - 1].geometry.coordinates;

    params.WaypointPositions = positions.features
      .slice(1, positions.features.length - 1)
      .map((feature) => feature.geometry.coordinates);
  }

  // DepartureTimeOptions
  if (departureTimeOptions.value === "default") {
    delete params.DepartNow;
    delete params.DepartureTime;
  }

  if (departureTimeOptions.value === "now") {
    delete params.DepartureTime;
    params.DepartNow = true;
  }

  if (departureTimeOptions.value === "custom") {
    delete params.DepartNow;
    params.DepartureTime = new Date(timestamp.value);
  }

  // CarModeOptions
  if (travelModeOptions.value === "Car") {
    params.CarModeOptions = {
      ...params.CarModeOptions,
      AvoidFerries:
        avoidOptions.value.findIndex((option) => option === "AvoidFerries") >
        -1,
    };
    params.CarModeOptions = {
      ...params.CarModeOptions,
      AvoidTolls:
        avoidOptions.value.findIndex((option) => option === "AvoidTolls") > -1,
    };
  }

  // TruckModeOptions
  if (travelModeOptions.value === "Truck") {
    params.TruckModeOptions = {
      ...params.TruckModeOptions,
      AvoidFerries:
        avoidOptions.value.findIndex((option) => option === "AvoidFerries") >
        -1,
    };
    params.TruckModeOptions = {
      ...params.TruckModeOptions,
      AvoidTolls:
        avoidOptions.value.findIndex((option) => option === "AvoidTolls") > -1,
    };

    if (
      truckHeight.value != null ||
      truckLength.value != null ||
      truckWidth.value != null
    ) {
      params.TruckModeOptions.Dimensions = {
        Height: truckHeight.value,
        Length: truckLength.value,
        Width: truckWidth.value,
        Unit: units[unitOfMeasurementOptions.value]["truck"]["dimension"],
      };
    }

    if (truckWeight.value != null) {
      params.TruckModeOptions.Weight = {
        Total: truckWeight.value,
        Unit: units[unitOfMeasurementOptions.value]["truck"]["weight"],
      };
    }
  }

  return params;
});

...
</script>

Then, add a function to initiate an Amazon Location Service’s client, call the API, and store the results in route as GeoJSON.

<script setup>
...

const calculateRoute = async () => {
  const client = new LocationClient({
    credentials: credentials,
    region: region,
  });

  if (
    requestParams.value.DeparturePosition &&
    requestParams.value.DestinationPosition
  ) {
    const command = new CalculateRouteCommand(requestParams.value);
    const response = await client.send(command);
    const routeFeature = lineString(
      response.Legs.flatMap((leg) => leg.Geometry.LineString),
      response.Summary
    );
    route.features.length = 0;
    route.features.push(routeFeature);
  }
};

...
</script>

Afterwards, add three map layers to display positions, their label, and calculated route on the map.

<script setup>
...

const initializeApp = async () => {
  ...

  map.on("load", () => {
    // Add a layer for rendering departure, waypoint, and destination positions on the map
    map.addLayer({
      id: "positions",
      type: "circle",
      source: { type: "geojson", data: positions },
      paint: {
        "circle-radius": 5,
        "circle-color": "#ffffff",
        "circle-stroke-color": "#00b0ff",
        "circle-stroke-width": 3,
      },
    });

    // Add a layer for rendering position labels on the map
    map.addLayer({
      id: "positions-label",
      type: "symbol",
      source: { type: "geojson", data: positions },
      layout: {
        "text-field": ["get", "title"],
        "text-variable-anchor": ["left"],
        "text-radial-offset": 0.5,
        "text-justify": "auto",
        "text-font": ["Noto Sans Regular"],
      },
    });

    // Add a layer for rendering routes on the map
    map.addLayer(
      {
        id: "route",
        type: "line",
        source: { type: "geojson", data: route },
        layout: {
          "line-join": "round",
          "line-cap": "round",
        },
        paint: {
          "line-color": "#00b0ff",
          "line-width": 5,
          "line-opacity": 0.7,
        },
      },
      "positions"
    );
  });
}

...
</script>

Next, add watchers to keep track of state changes, and re-calculate the route and re-render the map layers in reaction to changes.

<script setup>
...

// Route
watch(route, (value) => {
  map.getSource("route").setData(value);
});

watch(travelModeOptions, async () => {
  await calculateRoute();
});

watch(positions, async (value) => {
  map.getSource("positions").setData(value);
  map.getSource("positions-label").setData(value);
  await calculateRoute();
});

watch(unitOfMeasurementOptions, async () => {
  await calculateRoute();
});

watch(departureTimeOptions, async () => {
  await calculateRoute();
});

watch(timestamp, async () => {
  await calculateRoute();
});

watch(avoidOptions, async () => {
  await calculateRoute();
});

watch(truckHeight, async (value) => {
  if (value === "") {
    truckHeight.value = null;
  }
  await calculateRoute();
});

watch(truckWidth, async (value) => {
  if (value === "") {
    truckWidth.value = null;
  }
  await calculateRoute();
});

watch(truckLength, async (value) => {
  if (value === "") {
    truckLength.value = null;
  }
  await calculateRoute();
});

watch(truckWeight, async (value) => {
  if (value === "") {
    truckWeight.value = null;
  }
  await calculateRoute();
});

...
</script>

Finally, add some CSS to style the route calculator.

<style>
...

.n-card {
  max-width: 400px;
  margin: 10px 0 0 10px;
  box-shadow: 0 1px 2px -2px rgba(0, 0, 0, 0.08),
    0 3px 6px 0 rgba(0, 0, 0, 0.06), 0 5px 12px 4px rgba(0, 0, 0, 0.04);
}
</style>

Now, if you save your project and go to your browser, you will see the final result.

Wrap up

In this tutorial, you learned how you can build an online route planner that finds optimal routes between an origin, a destination, and up to 23 stops along the way (waypoints) for different modes of transportation, avoidances, and departure times. You can use this project as a starting point for building apps with maps and routing functionality and customize it to fit your purpose. Here are a few things you can do:

Include a number of different map styles using a layer control — see this post for an example.
Include a location search widget with geocoding, reverse-geocoding, and autocomplete support to allow users to search for starting point, waypoints, and destination via addresses or geographic coordinates — see this post for an example.
Customize the look and feel of the route calculator widget to match your brand and satisfy your use case.

I will end this post with a few notes:

Routing coverage — Amazon Location Service offers routing services from different data providers. Which data provider should you use for your project? The answer depends on your area of interest. Different data provides may gather and curate their data differently — for example, they may use a combination of authoritative sources, open data, and telemetry data to build their road network and traffic databases. That is why you may notice that a data provider has a better routing coverage or up-to-date traffic information for a region compared to other providers. To choose a data provider, find out what data providers are available in your region, compare their routing coverage in your area of interest, and choose the one that fits your project’s requirements. For example, visit Esri’s network analysis coverage, HERE’s car routing coverage and HERE's truck routing coverage to get more information about Esri’s and HERE’s coverage in your region.
Routing with Esri — If Esri is the data provider for your route calculator, the travel distance cannot be greater than 400km. If you specify Walking for the travel mode, the departure and destination positions must be within 40km.
Traffic-aware routing — Amazon Location Service takes traffic into account when calculating a route based on the departure time that you specify. You can specify to depart now, or you can provide a specific time that you want to leave, which will affect the route result by adjusting for traffic at the specified time. If you do not provide any value, it will use the best time of day to travel with the best traffic conditions to calculate the route.
Map matching — If you specify a position (departure, waypoint, or destination) that is not located on a road, Amazon Location Service will snap it to the nearest road.
Arrival time — The routing API response includes travel time, reported as DurationSeconds. You can use travel time and departure time to calculate arrival time.
Asset management and tracking use cases — If your application is tracking or routing assets that you use in your business, such as delivery vehicles or employees, you may only use HERE as your data provider. See section 82 of the AWS service terms.

The code for this project is on GitHub. I’d love to hear your feedback, so please reach out to me if you have any questions or comments.

How to add a location search widget to your web app using Amazon Location Service

abraham poorazizi — Wed, 13 Jul 2022 20:44:00 +0000

Location information comes in different forms and formats from geographical coordinates (or longitude & latitude) to addresses and to place names. A common use case, when building geospatial apps, is to allow users to search for places, and convert geographic coordinates into addresses and vice versa.

Amazon Location Service lets you add location search functionality to your web and mobile applications. It supports:

Converting text such as an address or a place name (or point of interest) into geographic coordinates, also known as geocoding.
Turning geographic coordinates into an address or a place name (or point of interest), also known as reverse-geocoding.
Responsive feedback to end-users as they are typing an address or a place name (or point of interest), also known as autocomplete or auto-suggest.

In this post, you will learn how you can add a location search widget to your web app using Amazon Location Service’s Places API. We will build the app using AWS Amplify and Vue — We will create, deploy, and manage AWS resources using Amplify CLI and we will build the app components using Amplify JavaScript and MapLibre GL JS. The app will have a basemap with navigation controls and a location search widget with geocoding, reverse-geocoding, and autocomplete support.

1. Install and configure AWS Amplify

Before you start

Create an AWS account, if you don’t have one already.
Install Node.js (version 12.x or greater) and npm (version 6.x or greater), if they are not already on your machine.

Now, install Amplify CLI.

npm install -g @aws-amplify/cli

Next, configure AWS Amplify. This will create a new IAM user with administrative access to your account to provision AWS resources for you.

amplify configure

Follow these steps to set up access to your AWS account:

Sign in to your AWS administrator account:
https://console.aws.amazon.com/
Press Enter to continue

Continue the process on the AWS Console. Create a user with AdministratorAccess-Amplify to your account to provision AWS resources for you.

Once you create the user, Amplify CLI will ask you to provide the accessKeyId and the secretAccessKey to connect Amplify CLI with your newly created IAM user.

Enter the access key of the newly created user:
? accessKeyId: ••••••••••••••••
? secretAccessKey:  ••••••••••••••••
This would update/create the AWS Profile in your local machine
? Profile Name: default

2. Create a new project

Create a new Vue project using Vite.

npm create vite@latest

Choose a name for your project and pick vue as the framework and variant.

✔ Project name: location-search-widget
✔ Select a framework: › vue
✔ Select a variant: › vue

Next, go into your project’s root directory and install the dependencies.

cd location-search-widget
npm install

Then, initialize AWS Amplify within your project’s root directory.

amplify init

Choose a name for your Amplify project, set your desired configurations, and select your authentication profile. Amplify CLI will then initialize your project.

? Enter a name for the project locationsearchwidget
The following configuration will be applied:

Project information
| Name: locationsearchwidget
| Environment: dev
| Default editor: Visual Studio Code
| App type: javascript
| Javascript framework: vue
| Source Directory Path: src
| Distribution Directory Path: dist
| Build Command: npm run-script build
| Start Command: npm run-script serve

? Initialize the project with the above configuration? Yes
Using default provider  awscloudformation
? Select the authentication method you want to use: AWS profile

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html

? Please choose the profile you want to use default

Next, install the AWS Amplify library for JavaScript.

npm install aws-amplify

Then, add the following code to src/main.js to configure Amplify within your Vue app.

...

import { Amplify } from "aws-amplify";
import awsconfig from "./aws-exports";

Amplify.configure(awsconfig);

...

Next, replace the content of App.vue with the following code.

<template>
</template>

<script setup>
</script>

<style>
</style>

Finally, add the following configuration to vite.config.

export default defineConfig({
  ...

  define: {
    global: {}
  }
});

3. Add auth configuration

We need to configure authentication in our app to specify how we want the frontend app access Amazon Location Service’s APIs. To do that, run the following command.

amplify add auth

We will stick with the defaults but you can choose advanced settings to make changes.

Using service: Cognito, provided by: awscloudformation

 The current configured provider is Amazon Cognito. 

 Do you want to use the default authentication and security configuration? Default configuration
 Warning: you will not be able to edit these selections. 
 How do you want users to be able to sign in? Username
 Do you want to configure advanced settings? No, I am done.

This will create an authentication resource, powered by Amazon Cognito, in your local environment.

4. Add a map

Amplify Geo is a new addition to the Amplify family. It provides APIs and UI components that enable developers to add location functionality such as maps and place search to their web and mobile apps. Amplify Geo APIs are powered by Amazon Location Service and its UI components are built as a plugin for MapLibre.

Now, let’s add a map. First, create a map resource using Amplify CLI.

amplify add geo

Choose a name for your map and pick your preferred auth configuration. We will stick with the defaults but you can choose advanced settings to change your data provider or map style, for example.

? Select which capability you want to add: Map (visualize the geospatial data)
✔ Provide a name for the Map: · locationsearchmap
✔ Who can access this Map? · Authorized and Guest users
Available advanced settings:
- Map style & Map data provider (default: Streets provided by Esri)

✔ Do you want to configure advanced settings? (y/N) · no

This will create a map resource in your local environment. Next, push the changes to AWS.

amplfiy push

It may take a few minutes for the changes to deploy. Once it is done, you will have your authentication and map resources set up and ready to use.

Now, let’s render the map we just created. First, install maplibre-gl-js-amplify, which is a plugin for MapLibre GL JS that makes it easy to integrate with Amplify Geo.

npm install maplibre-gl-js-amplify

Then, open App.vue and add a div container for the map.

<template>
   <div id="map"></div>
</template>

Next, add a new map instance with navigation controls.

<script setup>
import maplibregl from "maplibre-gl";
import { createMap } from "maplibre-gl-js-amplify";

async function initializeMap() {
    const map = await createMap({
        container: "map", 
        center: [-114.067375, 51.046333],
        zoom: 16,
        hash: true
    });

    map.addControl(new maplibregl.NavigationControl(), "bottom-right");
}

initializeMap();
</script>

Finally, add the following CSS to produce a full screen map.

<style>
@import "maplibre-gl/dist/maplibre-gl.css";

body {
  margin: 0;
  padding: 0;
}
#map {
  position: absolute;
  top: 0;
  bottom: 0;
  width: 100%;
}
</style>

Now, if you run npm run dev in your terminal and go to your browser, you will see an interactive map on the page.

5. Add a location search widget

The next step is to create a location search resource using Amplify CLI.

amplify add geo

Choose a name for your location search index and pick your preferred auth configuration. We will stick with the defaults but you can choose advanced settings to change your data provider, for example.

? Select which capability you want to add: Location search (search by places, addresses, coordinates)
✔ Provide a name for the location search index (place index): · locationsearchwidget
✔ Who can access this search index? · Authorized and Guest users
Available advanced settings:
- Search data provider (default: HERE)
- Search result storage location (default: no result storage)

✔ Do you want to configure advanced settings? (y/N) · no

This will create the backend resources for your project in your local environment. Next, push the changes to AWS.

amplfiy push

It may take a few minutes for the changes to deploy. Once it is done, you will have a location search resource set up and ready to use.

Now, let’s add a location search UI component to our map. First, import createAmplifyGeocoder into App.vue. This will create an instance of maplibre-gl-geocoder with some pre-defined settings.

<script setup>
...

import { createMap, createAmplifyGeocoder } from "maplibre-gl-js-amplify";

...
</script>

Next, add a new map control for the location search component.

<script setup>
...

async function initializeMap() {
   ...

   map.addControl(createAmplifyGeocoder(), "top-left");
}

...
</script>

Finally, import a CSS file into your app to style the location search component.

<style>
...

@import "@maplibre/maplibre-gl-geocoder/dist/maplibre-gl-geocoder.css";

...
</style>

Now, if you save your project and go to your browser, you will see a location search widget on the map.

6. Customizations

The Amplify Geo’s location search widget supports customization through a number of options, including:.

autocomplete, which provides suggestions as users type in their input.
bbox, which limits the results to a bounding box. By default, the location search widget returns results that are near the center of the map. If you add bbox, it will override the default behaviour.
countries, which limits the results to specified countries using ISO 3166 three letter country codes, for example CAN for Canada.
language, which limits the results to the specified language using a valid BCP 47 language code, for example en for English.
limit, which limits the maximum number of results returned in the API response. The default value is 5.

Amplify Geo forms appropriate queries based on your customizations and invokes Amazon Location Service’s Places API to perform location search operations. See all the supported options for customization on GitHub.

For this project, we will use autocomplete, countries, and language.

map.addControl(
    createAmplifyGeocoder({
      autocomplete: true,
      countries: "CAN",
      language: "en",
    }),
    "top-left"
  );

This will enable autocomplete and limit the search results to English and within Canada.

We will also add some UI customizations; we will use a custom icon for markers and add popups to markers. Download the SVG icon and put it in src/assets.

<script setup>
...

import markerIcon from "./assets/MarkerIcon.svg";

...

async function initializeMap() {
   ...

   const icon = new Image(35, 35);
   icon.src = markerIcon;

   map.addControl(
    createAmplifyGeocoder({
      ...

      marker: { element: icon },
      showResultMarkers: { element: icon },
      popup: { offset: 20 }
    }),
    "top-left"
  );
}

...
</script>

Finally, add some CSS to customize the style of the location search widget.

<style>
...

*:focus {
  outline: none !important;
}
.maplibregl-ctrl-top-left .maplibregl-ctrl {
  width: 400px !important;
  border-radius: 10px;
}
.suggestions {
  border-radius: 10px !important;
}
.maplibregl-ctrl-geocoder--input {
  height: 50px;
  padding: 0px 50px;
}
.maplibregl-ctrl-geocoder--icon-search {
  left: 15px;
  width: 25px;
  height: 35px;
}
.maplibregl-ctrl-geocoder--button {
  right: 15px !important;
  top: 15px !important;
}
.maplibregl-ctrl-geocoder--icon-loading {
  width: 25px;
  height: 25px;
  right: 15px !important;
  top: 15px !important;
}
</style>

Now, if you save your project and go to your browser, you will see the final result. You can search for addresses, place names, and geographic coordinates using the location search widget.

Wrap up

In this tutorial, you learned how you can add a location search widget to your web app using Amazon Location Service’s Places API. You can use this project as a starting point for building apps with maps and search functionality and customize it to fit your purpose. Here are a few things you can do:

Include a number of different map styles using a layer control — see my previous post for a walkthrough.
Use the location search widget options to provide a personalized experience for you users, for example setting the language property based on their IP or exposing geospatial filtering options using the bounding box property.
Adjust the position of map controls such as the navigation controls and the location search widget or change their style to match your brand.

If you’d like to delete the AWS resources that you have created for this project, run amplify delete.

The code for this project is on GitHub. I’d love to hear your feedback, so please reach out to me if you have any questions or comments.

How to build an interactive map using Amazon Location Service and MapLibre GL JS

abraham poorazizi — Mon, 06 Jun 2022 21:31:57 +0000

Maps are a visual representation of the world around us — they show us where things are and how they overlap and connect. We use interactive maps almost everyday to orient ourselves, discover things nearby, and find a way to get from one place to another. We also use interactive maps to create digital experiences, tell stories, and convey information — from developing a digital twin, to mapping active wildfires, to tracking the spread of infectious diseases, and to analyzing human mobility pattens.

In this post, I will show you how you can build an interactive map using Amazon Location Service, as the basemap provider, and MapLibre GL JS, as the map rendering engine. The map will have navigation controls, a layer control, and a marker with popup information.You can use this project as a starting point for building a web map and customize it to display your stores, real estate properties, or places you have visited on an interactive map.

Create an AWS account, if you don’t have one already, and let’s dive right in.

1. Create map resources

Amazon Location Service offers a set of map styles, professionally designed to support different applications and use cases — see Esri map styles and HERE map styles for more details. We’ll create a few map styles so that we can try them in our app later on.

To create a map style:

Head to the Amazon Location console and select Maps.
On the Maps page, choose Create map.
Add a Name and Description (optional) for the new map resource. Use esri-navigation for the name of the first map resource.
Choose Esri Navigation as the map style.
Agree to the Amazon Location Terms and Conditions, then choose Create map.

You have now created your first map. Repeat the steps and create four more maps with the following names and map styles:

Name: here-explore-truck, Map style: Here Explore Truck
Name: here-berlin, Map style: HERE Berlin
Name: esri-light-gray-canvas, Map style: Esri Light Gray Canvas
Name: esri-imagery, Map style: Esri Imagery

2. Grant access to map resources

Now, you need to grant access to the map resources that you created in step one by creating an Amazon Cognito identity pool and an IAM policy. This way a frontend application can send signed HTTP requests to Amazon Cognito and receive temporary, scoped-down credentials that are valid for an hour. Then, it can use those credentials to fetch map tiles from Amazon Location Service’s Maps API and render them in the browser.

To create an Amazon Cognito identity pool:

Head to the Amazon Cognito Console and select Create new identity pool. Note that your Amazon Cognito identity pool and Amazon Location Service’s resources must be in the same AWS region, for example us-west-2.
On the top-right corner, there is a section called Start from your business case. From the drop down, choose Grant access to AWS services, and choose Create identity pool.
Enter a Name for your identity pool.
From the Unauthenticated identities section, choose Enable access to unauthenticated identities.
Choose Create pool.
Create IAM roles that you want to use with your identity pool. Expand View Details and you’ll see two sections: first section is for creating an IAM role for authenticated identities and the second one is for creating an IAM role for unauthenticated identities.
Under the second section, expand the View Policy Document section, then choose Edit to add your policy.
Add the following policy to grant access to your maps resources.
Choose Allow to create your identity pool. The resulting identity pool follows the syntax {REGION}:{GUID}, for example us-west-2:930a7a7d-bd74-4f36-8575-1db02aa9870d.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Sid":"MapsReadOnly",
         "Effect":"Allow",
         "Action": "geo:GetMap*",
         "Resource": [
            "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/esri-navigation",
            "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/here-explore-truck",
            "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/here-berlin",
            "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/esri-light-gray-canvas",
            "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/esri-imagery"
         ]
      }
   ]
}

3. Set up project

Create an empty HTML file, index.html. Next, add a few dependencies:

MapLibre GL JS and its associated CSS for rendering the map and map controls.
AWS SDK for JavaScript for getting credentials from Amazon Cognito.
AWS Amplify core library for signing HTTP requests using AWS SigV4.

Then, create a new folder, img, in your project root directory. Finally, download the images from this repository and put them in the img folder.

<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">

    <title>Build an interactive map using Amazon Location Service and MapLibre GL JS</title>

    <!-- CSS dependencies -->
    <link href='https://unpkg.com/maplibre-gl@2.1.9/dist/maplibre-gl.css' rel='stylesheet' />

    <!-- JavaScript dependencies -->
    <script src='https://unpkg.com/maplibre-gl@2.1.9/dist/maplibre-gl.js'></script>
    <script src="https://sdk.amazonaws.com/js/aws-sdk-2.1145.0.min.js"></script>
    <script src="https://unpkg.com/@aws-amplify/core@4.5.6/dist/aws-amplify-core.min.js"></script>

  </head>
  <body>

  </body>
</html>

4. Add auth configurations

To get credentials from Amazon Cognito, first, enter your Cognito identity pool ID and configure your AWS region.

<script>
const identityPoolId = "COGNITO_IDENTITY_POOL_ID";

AWS.config.region = identityPoolId.split(":")[0];
</script>

Then, instantiate a credential provider using the Cognito identity pool you created earlier.

<script>
...

const credentials = new AWS.CognitoIdentityCredentials({
   IdentityPoolId: identityPoolId,
});
</script>

Next, add a function to automatically renew credentials before they expire.

<script>
...

async function refreshCredentials() {
    await credentials.refreshPromise();
    setTimeout(refreshCredentials, credentials.expireTime - new Date());
}
</script>

Finally, add a function to sign the HTTP requests sent to the Amazon Location Service’s Maps API using AWS SigV4 with the credentials obtained from Amazon Cognito. MapLibre GL JS map instances include a transformRequest option, which you can use to intercept and modify requests before they are made.

<script>
...

const { Signer } = window.aws_amplify_core;

function transformRequest(url, resourceType) {
    if (resourceType === "Style" && !url.includes("://")) {
        url = `https://maps.geo.${AWS.config.region}.amazonaws.com/maps/v0/maps/${url}/style-descriptor`;
      }

      if (url.includes("amazonaws.com")) {
        return {
          url: Signer.signUrl(url, {
            access_key: credentials.accessKeyId,
            secret_key: credentials.secretAccessKey,
            session_token: credentials.sessionToken,
          }),
        };
      }

    return { url };
}
</script>

5. Add a map

Add a div container for the map. MapLibre GL JS will render all map-related HTML elements, such as the map canvas and map controls including navigation controls and attributions, within this container.

<body>
    <div id="map"></div>
</body>

Then, add the following CSS to produce a full screen map.

<style>
    body {
      margin: 0;
      padding: 0;
    }

    #map {
      position: absolute;
      top: 0;
      bottom: 0;
      width: 100%;
    }
</style>

Next, call the refreshCredentials function to obtain the credentials when the page first loads and schedule the next credential refresh when they are about to expire.

<script>
...

   async function initializeApp() { 
        await refreshCredentials();
   }

   initializeApp();

</script>

Finally, add a new map instance. You can change the values for center and zoom to adjust your initial map view.

<script>
   async function initializeApp() { 
        ...

        const map = new maplibregl.Map({
            container: "map",
            center: [-114.067375, 51.046333],
            zoom: 16,
            style: "esri-navigation",
            hash: true,
            transformRequest,
        });
    }
</script>

Now, if you open the HTML file in your browser, you will see an interactive map on the page.

6. Add navigation controls

Add navigation controls to show zoom buttons and a compass on the map. You have four options for positioning the navigation controls on the map:

top-left
top-right
bottom-right
bottom-left

<script> 
    async function initializeApp() {
        ...

        map.addControl(new maplibregl.NavigationControl(), "bottom-right");
    }
</script>

7. Add a marker with popup information

Create a new popup and marker instances. Attach the popup to the marker and add them to the map.

<script>
    async function initializeApp() {
        ...

        const popup = new maplibregl.Popup({ offset: 35 }).setHTML(
            `<h3>Amazon YYC11</h3>
            <p>225 7 Ave SW, Calgary, AB T2P 2W2</p>
            <img src="img/yyc11.png" width="200" />
            `
        );

        const marker = new maplibregl.Marker()
            .setLngLat([-114.067375, 51.046333])
            .setPopup(popup)
            .addTo(map);
    }
</script>

Now, your map should look like the following screenshot.

8. Add a layer control

The layer control will consist of five cards, each representing a map style, used for switching between different map styles. First, add the following HTML to your code to create the layer control elements.

<body>
  ...

  <div class="layer-control">
    <div class="map-style esri-navigation">
      <img src="img/esri-navigation.png" alt="Esri Navigation" style="width:100%">
      <div class="text">
        Street
      </div>
    </div>
    <div class="map-style here-explore-truck">
      <img src="img/here-explore-truck.png" alt="HERE Explore Truck" style="width:100%">
      <div class="text">
        Truck
      </div>
    </div>
    <div class="map-style here-berlin">
      <img src="img/here-berlin.png" alt="HERE Berlin" style="width:100%">
      <div class="text">
        3D
      </div>
    </div>
    <div class="map-style esri-light-gray-canvas">
      <img src="img/esri-light-gray-canvas.png" alt="Esri Light Gray Canvas" style="width:100%">
      <div class="text">
        Light
      </div>
    </div>
    <div class="map-style esri-imagery">
      <img src="img/esri-imagery.png" alt="Esri Imagery" style="width:100%">
      <div class="text">
        Satellite
      </div>
    </div>
  </div>

</body>

Then, add the following CSS to style the layer control.

<style>
    ...

    .layer-control {
      position: absolute;
      right: 53px;
      bottom: 30px;
      max-width: 400px;
      padding: 8px;
      border-radius: 5px;
      box-shadow: 0 1px 4px rgb(0 0 0 / 30%);
      background: #fff;
      display: flex;
      justify-content: center;
      z-index: 2;
    }

    .map-style {
      width: 48px;
      height: 60px;
      border-radius: 10px;
      margin: 5px;
    }

    .map-style:hover {
      cursor: pointer;
    }

    .map-style img {
      border-radius: 10px;
    }

    .map-style .text {
      font-size: 12px;
      font-family: Arial, sans-serif;
      color: #333;
      margin: 2px;
      text-align: center;
    }

  </style>

Finally, add the following logic so that when you click on a map style, the app will change the basemap accordingly.

<script>
    async function initializeApp() {     
      ...

      document.querySelector(".map-style.esri-navigation")
        .addEventListener("click", function (event) {
          map.setStyle("esri-navigation")
        });
      document.querySelector(".map-style.here-explore-truck")
        .addEventListener("click", function (event) {
          map.setStyle("here-explore-truck")
        });
      document.querySelector(".map-style.here-berlin")
        .addEventListener("click", function (event) {
          map.setStyle("here-berlin")
        });
      document.querySelector(".map-style.esri-light-gray-canvas")
        .addEventListener("click", function (event) {
          map.setStyle("esri-light-gray-canvas")
        });
      document.querySelector(".map-style.esri-imagery")
        .addEventListener("click", function (event) {
          map.setStyle("esri-imagery")
        });
    }
</script>

Now, your app has a layer control that you can use to switch between different map styles.

Wrap up

In this tutorial, we learned how to use Amazon Location Service and MapLibre GL JS to build an interactive map. You can use this project as a starting point for building web maps and customize it to fit your purpose. You can also add more things to it, for example, you can add more markers to highlight your favourite hiking trails, advertise your rental properties, or display your stores on a map.
You can check out this GitHub repository, if you want to dive into the code. I’d love to hear your feedback, so please reach out to me if you have any questions or comments.

I will end this post with a few tips:

Map styles — Amazon Location Service offers a set of different map styles; how do you choose a map style for your project? The answer depends on your use case:
- If your application uses map as a main source of information like a rental property app, ride sharing app, or a routing and navigation app then use a map style with detailed information about roads, landmarks, and buildings. Use Esri Navigation, Esri Imagery, or HERE Berlin for such use cases.
- If your application is focused on transportation by trucks, then use a map style that highlights truck-related attributes and restrictions such as width and height. Use HERE Explore Truck for this use case.
- If your application uses map as a background for data visualization then use a map style with neutral colors and minimal features to draw attention to your thematic content. Use Esri Light Gray Canvas or Esri Dark Gray Canvas for such use cases.
Data quality and map coverage — Amazon Location Service offers map styles from different data providers. Which data provider should you use for your project? The answer depends on your area of interest. Each data provider gathers and curates their data using different techniques — for example they may use a combination of authoritative sources, open data, and AI-assisted mapping to compile their databases and basemaps. So the quality of data sources and the accuracy of their methods have a direct effect on the quality of their basemaps. That is why you may notice that a data provider has a better map coverage or up-to-date, higher resolution imagery for a region compared to other providers. To choose a data provider, pick a few map styles from different providers and compare their map coverage in your area of interest and choose the one that fits your project’s requirements.
Asset management and tracking use cases — If your application is tracking or routing assets that you use in your business, such as delivery vehicles or employees, you may only use HERE as your data provider. See section 82 of the AWS service terms.
Service quotas — There are limits on the number of Amazon Location Service’s resources you can have per AWS account and AWS region. There are also limits on the number of requests per second you can send to an Amazon Location Service’s APIs — see Amazon Location Service quotas for more information. However, the quotas for all the APIs offered by Amazon Location Service are adjustable. This means that you can use the Service Quotas console to request for an increase, if you require a higher quota.
Deployment — When you deploy your website you may want to limit browser access to your Amazon Location Service’s resources to certain URLs. To do so, add the following condition to the IAM policy you created in step 2 to deny access to your map resources from all referring websites except example.com.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "MapsReadOnly",
            "Effect": "Allow",
            "Action": "geo:GetMap*",
            "Resource": [
                "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/esri-navigation",
                "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/here-explore-truck",
                "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/here-berlin",
                "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/esri-light-gray-canvas",
                "arn:aws:geo:{AWS_REGION}:{AWS_ACCOUNT_ID}:map/esri-imagery"
            ],
            "Condition": {
                "StringLike": {
                    "aws:referer": [
                        "https://example.com/*",
                        "https://www.example.com/*"
                    ]
                }
            }
        }
    ]
}