How to use Vector Enrichment Jobs for Reverse Geocoding

This notebook's CI test result for us-west-2 is as follows. CI test results in other regions can be found at the end of the notebook.

This notebook demonstrates how to use Amazon SageMaker geospatial capabilities to perform reverse geocoding and visualize the results.

Reverse geocoding allows you to convert geographic coordinates (latitude, longitude) to human-readable addresses powered by Amazon Location Service. With Amazon SageMaker geospatial capabilities it is possible to perform batch reverse geocoding via a Vector Enrichtment Job (VEJ). The input for this kind of VEJ is a CSV file containing longitude and latitude coordinates, and the VEJ will enrich the CSV with the address number, country, label, municipality, neighborhood, postal code and region of that location.

The workflow is as follows:

• Step 1: Import SageMaker geospatial capabilities SDK
• Step 2: Inspect input data and upload to S3
• Step 3: Create an Vector Enrichtment Job (VEJ)
• Step 4: Export VEJ output to S3
• Step 5: Visualize enriched data set in Amazon SageMaker geospatial Map SDK

Prerequisites

This notebook runs with Kernel Geospatial 1.0. Note that the following policies need to be attached to the execution role that you used to run this notebook:

• AmazonSageMakerFullAccess
• AmazonSageMakerGeospatialFullAccess

You can see the policies attached to the role in the IAM console under the permissions tab. If required, add the roles using the 'Add Permissions' button.

In addition to these policies, ensure that the execution role's trust policy allows the SageMaker-GeoSpatial service to assume the role. This can be done by adding the following trust policy using the 'Trust relationships' tab:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "sagemaker.amazonaws.com",
                    "sagemaker-geospatial.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Import SageMaker geospatial capabilities SDK

Dataset: California Housing Data

The California Housing dataset contains information from the 1990 California census. We will use the dataset to demonstrate how to resolve the latitude and longitude into human readable address information. The dataset contains the following columns:

• MedInc - average income
• HouseAge - housing average age
• TotalRooms - total rooms
• TotalBedrms - total bedrooms
• Population - population
• Households - amount of households
• Latitude - latitude
• Longitude - longitude

The California Housing dataset was originally published in:

Pace, R. Kelley, and Ronald Barry. "Sparse spatial autoregressions." Statistics & Probability Letters 33.3 (1997): 291-297.

Inspect input data and upload to S3

The following cells will write the dataset as a CSV and upload the CSV to a S3 bucket. The CSV file needs to contain a header line. The header names are used in the ReverseGeocodingConfig for the Vector Enrichment Job for mapping the CSV columns to the expected attributes.

Create an Vector Enrichtment Job

The following cell will define and start a Vector Enrichment Job for reverse geocoding. The longitude and latitude headers of the CSV file are mapped to be used as input for the reverse geocoding implementation.

Export VEJ output to S3

An export of a reverse geocoding VEJ produces a CSV which contains all columns of the input CSV and is extended with the following columns:

• reverse_geo.address_number
• reverse_geo.country
• reverse_geo.label
• reverse_geo.municipality
• reverse_geo.neighborhood
• reverse_geo.postal_code
• reverse_geo.region
• reverse_geo.status

The following cell will export the output of the VEJ into a S3 bucket.

Visualize enriched data set in Amazon SageMaker geospatial Map SDK

The following cells will create an interactive map with the Amazon SageMaker geospatial Map SDK. The output data of the VEJ will be loaded from S3 into a pandas dataframe and then visualized in the embedded map.

Load VEJ output into pandas dataframe

Render embedded map

Add output data to map visualization

The following cell will add the output data as points to the map. When you hover over single items, it'll display the reverse_geo.label which resembles the address of the given point.

Notebook CI Test Results

This notebook was tested in multiple regions. The test results are as follows, except for us-west-2 which is shown at the top of the notebook.