Prerequisites for using Amazon Location Service
Below describe what you need to do to use Amazon Location Service. You must have an AWS account and have set up access to Amazon Location for users that want to use it.
1. Sign up for AWS
If you're new to Amazon Web Services AWS, sign up for an AWS account.
To create an AWS account
1. Open https://portal.aws.amazon.com/billing/signup.
2. Choose Create an AWS Account.
3. Follow the instructions.
2. Manage access to your AWS resources using IAM
AWS Identity and Access Management (IAM) is a web service that enables you to manage access to your AWS resources by controlling who is authenticated and authorized to use resources.
When you sign up for an AWS account, you start with a root account.
There are two different types of users in AWS:
• Root user — The administrative account used by the account owner to allow full access to all resources in the account.
• IAM user — An account created by the root user, which is granted targeted access to resources using attached permissions specified by an IAM policy.
You cannot use IAM policies to explicitly deny the root user access to resources. Therefore, it's a best practice to avoid using your AWS root user account for everyday tasks where it’s not required. We recommend that you set up and use an IAM user account with targeted access and permissions to perform specific tasks and access resources. This enables you to lock away the access keys for the root user.
When you create a new IAM user, you can view and download your user credentials, which are your account ID, account key ID, and secret key. You will need these later to set up authentication to access AWS resources.
**Important**
This is the only time that you can view and download your secret access key. You can select the Download .csv option to keep record of your access key ID and secret access key. If you lose your credentials, you can create new credentials.
It is recommended to create an IAM User with AdministratorAccess policy to deal with all the necessary operations in AWS as shown below:
General Overview
Maps
The following is an overview of how to create and use map resources:
1. You create a map resource in your AWS account by selecting a map style from a data provider.
2. You can then select and install the SDK that matches your development environment and applications.
3. To display a map in your application, combine a map resource with a rendering library, such as Amplify, MapLibre GL, or Tangram.
4. You can then integrate monitoring by using services, such as Amazon CloudWatch and AWS CloudTrail with Amazon Location.
Map styles
When you create a map resource, you must choose a map style for that resource. Map styles define the look of the rendered map. For example, the following image shows the same data provider with two different styles from different map resources in Amazon Location. One style is a typical road style, based on the vector data in the map. The other includes raster data showing satellite imagery. The style may change as you zoom in or out on the map, but typically styles have a consistent theme. It's possible to override parts or all of the style information before passing it to the map rendering library.
Map rendering
To render a map in your application, you will typically use a map rendering library. There are several common options for libraries to use:
• Amplify – Amplify is an open source framework for building applications for the web, iOS, Android, and more. Amplify includes libraries specifically for creating Amazon Location based applications, including rendering maps. Amplify uses MapLibre GL to render the map, but provides additional functionality that is specific to Amazon Location Service to make it more efficient to use, and also adding search and other functionality.
• MapLibre GL – MapLibre GL is an open source library specifically for rendering interactive maps. MapLibre GL includes the ability to render raster and vector data from a data source (such as an Amazon Location map resource). You can extend MapLibre GL to draw your own data on the map.
• Tangram – Tangram is an alternative open source library that renders interactive maps, similar to MapLibre GL.
The map rendering library pulls data from Amazon Location Service at runtime, rendering the map data based on the map resource you select. The map resource defines the data provider and map style that will be used.
The following image shows how the map resource is used in Amazon Location Service along with a map rendering library to create the final map.
1. You create a map resource in Amazon Location Service, using the AWS Management Console. This defines the data provider and the map style that you want to use.
2. Your application includes a map rendering library. You give the map rendering library the name of the map resource to use. The map rendering library pulls data and style information for that map resource from Amazon Location and renders the map on screen.
Maps terminology
Map resource
Allows you to access map data from a selected provider. Use the map resource to fetch map tiles that contain map data and a style descriptor to specify how features render on a map.
Basemap
Provides geographic context to your map, which is stored as vector tile layers. Tile layers include geographical context such as street names, buildings, and land use for visual reference.
Vector
Vector data is shape data made up of points, lines, and polygons. It is often used to store and display roads, locations, and areas on a map. A vector shape can also be used as icons for markers on a map.
Raster
Raster data is image data, made up of a grid, usually of colors. It is often used to store and display a representation of continuous data on maps, such as terrain, satellite imagery, or heat maps. Raster images can also be used as images or icons.
Map Style
Vector data does not inherently include information about how to draw the layers of data to create the final map. A map style defines color and other style information for the data to define how it will look when rendered. Map resources include style information for the map.
Vector tile
A tile format that stores map data using vector shapes. This data results in a map that can adjust to the display resolution, and selectively render features in a number of ways, while maintaining a small file size for optimal performance. Supported vector file format: Mapbox Vector Tiles (MVT).
Glyph file
A binary file containing encoded Unicode characters. Used by a map renderer to display labels.
Sprite file
A Portable Network Graphic (PNG) image file that contains small raster images, with location descriptions in a JSON file. Used by a map renderer to render icons or textures on a map.
Places search
A key function of Amazon Location Service is the ability to search the geolocation information. Amazon Location provides this functionality via the Place index resource.
You can use the place index APIs to search for:
• Points of interest, such as restaurants and landmarks. Search by name, and optional location to search around, and receive a list of options ordered by relevance.
• A street address, receiving a latitude and longitude for that address. This is known as geocoding.
• A latitude and longitude position, receiving the associated street address or other information about the location. This is known as reverse geocoding.
• A partial or misspelled free-form text query, typically as a user types. This is known as autocomplete, autosuggest, or fuzzy matching.
The place index includes which data provider to use for the search.
**Note**
Map data and other geolocation information, including exact locations, can vary across data providers. As a best practice, use the same data provider for your place index, map, and other Amazon Location resources. For example, if the places returned by your place index do not match the location of the same places provided by your map resource, you can place a marker in what appears to be the wrong location on the map.
Entering into specifics
What is a data provider?
Use Amazon Location Service to access geolocation resources from multiple data providers through your AWS account without requiring third-party contracts or integrations. This can help you focus on building your application, without having to manage third-party accounts, credentials, licenses, and billing.
The following Amazon Location services use data providers.
• Maps – Choose styles from different map providers when you create a map resource. You can use map resources to build an interactive map to visualize data.
• Places – Choose a data provider when you create a place index resource to support queries for geocoding, reverse geocoding, and searches.
• Routes – Choose a data provider to support queries for route calculations in different geographies and applications when you create a route calculator resource. With your chosen data provider, Amazon Location Service enables you to calculate routes based on up-to-date road network data, live traffic data, planned closures, and historic traffic patterns.
Each provider gathers and curates their data using different means. They may also have varying expertise in different regions of the world. This section provides details about our data providers. You may select any data provider based on your preference.
Amazon Location Services maps support two data providers: ESRI and HERE.
ESRI Map Provider
Amazon Location Service uses Esri's location services to help AWS customers to use maps, geocode, and calculate routes effectively. Esri’s location services are built with high-quality, authoritative, and readyto-use location data, curated by expert teams of cartographers, geographers, and demographers.
Esri map styles
Amazon Location Service supports the following Esri map styles when creating a map resource:
**Note: Esri map styles that are not listed in this section are currently not supported.
1. Esri Light Map. Map style name: VectorEsriTopographic
This provides a detailed basemap for the world symbolized with a classic Esri map style. This includes highways, major roads, minor roads, railways, water features, cities, parks, landmarks, building footprints, and administrative boundaries.
This basemap is compiled from a variety of authoritative sources from several data providers, including the US Geological Survey (USGS), US Environmental Protection Agency (EPA), US National Park Service (NPS), Food and Agriculture Organization of the United Nations (FAO), Department of Natural Resources Canada (NRCAN), HERE, and Esri. Data for select areas is sourced from OpenStreetMap contributors. Additionally, data is provided by the GIS community.
2. Esri World Streets. Map style name: VectorEsriStreets
This vector tile layer provides a detailed basemap for the world symbolized with a classic Esri street map style. The vector tile layer is similar in content and style to the World Street Map raster map.
This vector tile layer provides unique capabilities for customization and high-resolution display.
This comprehensive street map includes highways, major roads, minor roads, railways, water features, cities, parks, landmarks, building footprints, and administrative boundaries. The vector tile layer is built using the same data sources used for the raster basemap World Street Map raster map and other Esri basemaps.
3. Esri World Navigation. Map style name: VectorEsriNavigation
This map provides a detailed basemap for the world symbolized with a custom navigation map style that's designed for use during the day in mobile devices.
This comprehensive street map includes highways, major roads, minor roads, railways, water features, cities, parks, landmarks, building footprints, and administrative boundaries. The vector tile layer in this map is built using the same data sources used for the World Street Map and other Esri basemaps.
4. Esri Dark Gray Canvas. Map style name: VectorEsriDarkGrayCanvas
This map provides a detailed vector basemap for the world symbolized with a dark gray, neutral background style with minimal colors, labels, and features that's designed to draw attention to your thematic content.
This map includes highways, major roads, minor roads, railways, water features, cities, parks, landmarks, building footprints, and administrative boundaries. The vector tile layers in this map are built using the same data sources used for the Dark Gray Canvas raster map and other Esri basemaps.
5. Esri Light Gray Canvas. Map style name: VectorEsriLightGrayCanvas
This map provides a detailed basemap for the world symbolized with a light gray, neutral background style with minimal colors, labels, and features that's designed to draw attention to your thematic content.
This vector tile layer is built using the same data sources used for the Light Gray Canvas and other Esri basemaps. The map includes highways, major roads, minor roads, railways, water features, cities, parks, landmarks, building footprints, and administrative boundaries.
7. Esri Imagery. Map style name: RasterEsriImagery
This map provides one meter or better satellite and aerial imagery in many parts of the world and lower resolution satellite imagery worldwide.
The map includes 15m imagery at small and mid-scales (~1:591M down to ~1:72k) and 2.5m SPOT Imagery (~1:288k to ~1:72k) for the world. The map features 0.5m resolution imagery in the continental United States and parts of Western Europe from Maxar. This map features additional Maxar submeter imagery in many parts of the world. In other parts of the world, the GIS User Community has contributed imagery at different resolutions. In select communities, very high resolution imagery (down to 0.03m) is available down to ~1:280 scale.
Coverage: Esri
You can use Esri as a data provider to support queries for geocoding, reverse geocoding, and searches when you create a place index resource, or to support queries to calculate a route when you create a route calculator resource.
Esri provides different levels of data quality in different regions of the world.
HERE Technologies
Amazon Location Service uses HERE Technologies’ location services to help AWS customers use maps, geocode, and calculate routes effectively. HERE's location data offers a location-centric platform that's open, secure, and private. By selecting HERE location data, you are selecting accurate, fresh, and robust data that's deployed natively on the AWS Cloud.
HERE map styles
Amazon Location Service supports the following HERE map styles when creating a map resource:
HERE map styles that are not listed in this section are currently not supported
1. HERE Contrast (Berlin). Map style name: VectorHereContrast
A detailed base map of the world that blends 3D and 2D rendering. The high contrast street map includes highways, major roads, minor roads, railways, water features, cities, parks, landmarks, building footprints, and administrative boundaries.
2. HERE Explore. Map style name: VectorHereExplore
A detailed, neutral base map of the world. The street map includes highways, major roads, minor
roads, railways, water features, cities, parks, landmarks, building footprints, and administrative
boundaries. Includes a fully designed map of Japan.
3. HERE Explore Truck. Map style name: VectorHereExploreTruck
A detailed, neutral base map of the world. The street map builds on top of the HERE Explore style, and highlights track restrictions and attributes (including width, height, and HAZMAT) with symbols and icons, to support use cases within transport and logistics.
Coverage: HERE
You can use HERE as a data provider to support queries for geocoding, reverse geocoding, and searches when you create a place index resource, or to support queries to calculate a route when you create a route calculator resource.
HERE provides different levels of data quality in different regions of the world.
Amazon Location Regions and endpoints
Amazon Location is available in the following AWS Regions:
Endpoints
The general syntax for an Amazon Location regional endpoint is as follows:
protocol://service-code.geo.region-code.amazonaws.com
Within this syntax, Amazon Location uses the following service codes:
For example, the regional endpoint for Amazon Location Maps for US East (N. Virginia) would be: https://maps.geo.us-east-1.amazonaws.com
Using Amazon Location Maps in your application. Steps to follow
I - Create a map resource
To create a map resource:
1. In the Amazon Location console, on the Maps page, choose Create map to preview map styles.
2. Add a name and description for the new map resource.
3. Choose a map.
4. Agree to the Amazon Location Terms and Conditions, then choose Create map. You can interact with the map that you've chosen: zoom in, zoom out, or pan in any direction.
5. To allow your users to switch styles (for example, to allow them to switch between satellite imagery and vector style), you must create a map resource for each style.
You can delete resources with map styles that you don’t want to use on the Maps home page in the console
II – Create a place index resource
Begin by creating a place index resource in your AWS account. This will allow to search by coordinates using the map resource.
**Note **: It is important the place index resource has the same Data Provider (ESRI / HERE) than the map resource.
When you create a place index resource, you can choose from the data providers available to support queries for geocoding, reverse geocoding, and searches:
Esri – For more information about Esri's coverage in your region of interest, see Esri geocoding coverage in this guide.
HERE Technologies – For more information about HERE's coverage in your region of interest, see HERE geocoding coverage in this guide.
You can do this using the Amazon Location Service console, the AWS CLI, or the Amazon Location APIs.
To create a place index resource using the Amazon Location Service console
Open the Amazon Location Service console at https://console.aws.amazon.com/location/.
In the left navigation pane, choose Place indexes.
Choose Create place index.
Fill out the following boxes:
Name – Enter a name for the place index resource. For example, ExamplePlaceIndex. Maximum 100 characters. Valid entries include alphanumeric characters, hyphens, periods, and underscores.
ExamplePlaceIndex
Description – Enter an optional description.
Under Data providers, choose an available data provider to use with your place index resource.
Under Data storage options, specify if you intend to store search results from your place index resource.
(Optional) Under Tags, enter a tag Key and Value. This adds a tag your new place index resource. For more information, see Tagging your resources.
III - Authenticating your requests
To use Amazon Location Service, your AWS account must be granted access to the resources and APIs that make up Amazon Location. To grant access to an AWS account, use AWS Identity and Access Management (IAM), and create a policy that grants access to the resources that you want. For more information about IAM and Amazon Location, see Identity and Access Management for Amazon Location Service.
You can also use Amazon Cognito to grant anonymous access, or to use your own separate authentication with Amazon Location Service.
Allowing unauthenticated guest access to your application using Amazon Cognito
You can use Amazon Cognito authentication as an alternative to directly using AWS Identity and Access Management (IAM) with both frontend SDKs and direct HTTPS requests.
You may want to use this form of authentication for the following reasons:
Amazon Cognito provides authentication, authorization, and user management for web and mobile apps. You can use Amazon Cognito unauthenticated identity pools with Amazon Location as a way for applications to retrieve temporary, scoped-down AWS credentials.
For more information, see Getting Started with User Pools in the Amazon Cognito Developer Guide.
Create an Amazon Cognito identity pool
You can create Amazon Cognito identity pools to allow unauthenticated guest access to your application through the Amazon Cognito console, the AWS CLI, or the Amazon Cognito APIs.
Important
The pool that you create must be in the same AWS account and AWS Region as the Amazon Location Service resources that you're using.
You can use IAM policies associated with unauthenticated identity roles with the following actions:
Including other Amazon Location actions will have no effect, and unauthenticated identities will be unable to call them.
To create an identity pool using the Amazon Cognito console
Amazon Cognito user pools – Manage Authenticated Users
A user pool is a user directory in Amazon Cognito. With a user pool, your users can sign in to your web or mobile app through Amazon Cognito. Your users can also sign in through social identity providers like Google, Facebook, Amazon, or Apple, and through SAML identity providers. Whether your users sign in directly or through a third party, all members of the user pool have a directory profile that you can access through a Software Development Kit (SDK).
User pools provide:
After successfully authenticating a user, Amazon Cognito issues JSON web tokens (JWT) that you can use to secure and authorize access to your own APIs, or exchange for AWS credentials.
Amazon Cognito provides token handling through the Amazon Cognito user pools Identity SDKs for JavaScript, Android, and iOS. See Getting started with user pools and Using tokens with user pools.
The two main components of Amazon Cognito are user pools and identity pools. Identity pools provide AWS credentials to grant your users access to other AWS services. To enable users in your user pool to access AWS resources, you can configure an identity pool to exchange user pool tokens for AWS credentials. For more information see Accessing AWS services using an identity pool after sign-in and Getting started with Amazon Cognito identity pools (federated identities).
Using AWS Maps Outsystems Component.
This component receives several input parameters:
Explaining Authorization considerations used in the component:
Before start talking about Authorization, please make sure you created before this step a Map and also a Place Index. You will need the arn from both resources later in this walkthrow.
The component was implemented to provide access to unauthenticated users to Amazon Location Services resources using an Amazon Cognito Identity Pool, so we need to apply the needed changes on AWS Location Services.
Create an Amazon Cognito Identity Pool, make sure you create new roles for Unauthenticated and Authenticated roles by clicking on the links create new role, and also enable the access to unauthenticated entities as shown below, and after that finish the creation of the Amazon Cognito Identity Pool.
Copy the name for the new created role for Unauthenticated users. After this it is necessary to update the permissions for that role to allow access to amazon location services. We are doing this to simplify maps integration from Amazon Location Services in Outsystems.
For being able to update the permissions of the unauthenticated role we need to follow several steps:
1. Go to Identity and Access Management (IAM) Console.
2. Check in the Access Management section in the right for Roles and later open the name of the created unauthenticated in our Amazon Cognito Identity Pool.
3. Open the unauthenticated role, click on Add Permissions and later in Create Inline Policy as shown below.
4. After open the Create policy page, select the Json tab as shown below:
5. Then copy and paste the json below into the json text area above to add amazon localization services needed permissions to the policy and replace in the Resource section the arn of your created map and place index resources.
{
"Version": "2012-10-17",
"Statement": [
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"geo:DescribePlaceIndex",
"geo:SearchPlaceIndexForText",
"geo:DescribeMap",
"geo:GetMapGlyphs",
"geo:SearchPlaceIndexForSuggestions",
"geo:UpdateMap",
"geo:GetMapSprites",
"geo:GetMapStyleDescriptor",
"geo:SearchPlaceIndexForPosition",
"geo:UpdatePlaceIndex",
"geo:GetMapTile"
],
"Resource": [
"arn:aws:geo:us-east-1:175713957655:map/demo.map",
"arn:aws:geo:us-east-1:175713957655:place-index/demo.place"
]
}
6. Click on Review policy, add a Name for the policy. In my case I used demomap_readwrite, but you can choose whatever the name you prefer and click Create Policy.
7. After the previous steps you should have the role like it is shown below:
Important Considerations:
You need to create a Map resource, a Place Index and create an Amazon Cognito Identity Pool and allow the access for unauthenticated users as was described in the previous tutorial, you should have everything ready to display the map in Outsystems using this component.
The map and the place index need to have the same provider (ESRI or HERE).
Be careful, Amazon Location Services coordinates works in a different way than Google maps. Amazon Location Services uses coordinates like (longitude, latitude), on the contrary than Google Maps that uses coordinates like (latitude, longitude). Amazon Location Services updated their format to match the one used in MapLibreGL Js, very useful when rendering maps, markers and popups, between other things.
The component includes a validation for invalid coordinates: Latitude should be between (-90 to 90) and Longitude between (-180 to 180).
It also includes an action to get the current location (coordinates) of the user.
There is a structure to hold marker information with the structure of Longitude and Latitude. The workflow to display a marker is the following: