Use 3D map library with API key function of Amazon Location Service
Tags: amazonlocationservice, itowns, aws, foss4g
Published: 2023-08-02 12:13:24

This article is an English translation of an article published in the AWS Japan official web magazine "builders.flash".
https://aws.amazon.com/jp/builders-flash/202308/use-3d-map-library-location-service
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/page.png) 

<br>

Today, I will show you how to use the 3D map library with the API key feature of the Amazon Location Service, which allows you to build location-based applications in an AWS environment.

<br>

In the initial release of Amazon Location Service, only Amazon Cognito was supported as authentication. The amount of code required to configure the system was large, and it was not always compatible with the map library. However, in July 2023, the API key function was released to the public, and the method of assigning API keys to URLs, commonly used in the location information industry, is finally available.

<br>

The 3D Map Library differs from ordinary map libraries in that it specializes in representing 3D objects and 3D data. [Cesium](https://cesium.com) and [iTowns](https://www.itowns-project.org) are two widely used open-source 3D map libraries. In this article, I will show you how to build location-based applications using iTowns in particular. As for Cesium, it is possible to display map styles in combination with the [MVTImageryProvider](https://github.com/hongfaqiu/MVTImageryProvider) library. However, as of July 2023, some map styles are not yet supported, and Amazon Location Service map styles are among them, so they are not covered in this article.

<br>

When using the Amazon Location Service, I recommend [MapLibre GL JS](https://maplibre.org), which I introduced in my previous article, "[Amazon Location Service and AWS Amplify to Use Various Map Library](https://dev.to/aws-heroes/amazon-location-service-and-aws-amplify-to-use-various-map-library-4mmk)," but you can also use any map library you like, including iTowns this time. I hope you will choose the map library of your choice, including iTowns!

### [Cesium](https://cesium.com)
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/cesium.png)  

### [iTowns](https://www.itowns-project.org)
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/itowns.png)  


## Advance Preparation
I will extend the existing starter to build an Amazon Location Service environment. This starter is configured to allow easy use of the map library. Please try to fork or download the starter and see how it works in your environment.

### iTowns Starter
### [itowns-starter](https://github.com/dayjournal/itowns-starter)  
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/itowns_starter.png)  

Verified version at the time of writing
- node v18.1.0
- npm v8.19.2

### How to use the starter
Install the package

```bash
npm install
```

Start local server

```bash
npm run dev
```

![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/starter.png)  

<br>

## Configure Amazon Location Service
Next, configure the Amazon Location Service. Create a map and API key, and note the map name and API key.

Click AWS Management Console → Amazon Location Service → "Maps."
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/console_01.png)

Click "Create Map."
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/console_02.png)

Set the map name, map style, API key, and API key name, and check "Agree to Terms of Use" → Click "Create Map." When publishing externally, you must also set the referrer for the API key.
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/console_03.png)

When the map creation is complete, click "API Key."
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/console_04.png)

Click the name of the API key you created.
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/console_05.png)

Click "Show API Key Value" → Note down the API key displayed.
![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/console_06.png)  

<br>

## Building the Application
Finally, I will show you how to display an Amazon Location Service map using your API key. Update the starter "main.ts" and "vite.config.ts" respectively. In detail, set the map style URL to "https://maps.geo.[region].amazonaws.com/maps/v0/maps/[mapName]/style-descriptor?key[apiKey]". Here, set "region" to the region name, "mapName" to the map name, and "apiKey" to the API key.

#### File Configuration

```sh
.
├── LICENSE
├── README.md
├── dist
│   ├── assets
│   └── index.html
├── docs
├── img
├── index.html
├── node_modules
├── package-lock.json
├── package.json
├── src
│   ├── itowns.d.ts
│   ├── main.ts
│   ├── style.css
│   └── vite-env.d.ts
├── tsconfig.json
└── vite.config.ts
```

#### package.json

```json
{
    "name": "itowns-starter",
    "version": "2.39.0",
    "description": "",
    "scripts": {
        "dev": "vite",
        "build": "tsc && vite build",
        "preview": "vite preview"
    },
    "keywords": [],
    "author": "Yasunori Kirimoto",
    "license": "ISC",
    "devDependencies": {
        "typescript": "^5.0.4",
        "vite": "^4.3.5"
    },
    "dependencies": {
        "buffer": "^6.0.3",
        "itowns": "^2.39.0"
    }
}
```

#### main.ts

```typescript
import './style.css'
import * as itowns from 'itowns';

const map = document.getElementById('map');
const placement = {
    coord: new itowns.Coordinates('EPSG:4326', 150.0, 30.0),
    heading: -50,
    range: 10000000,
    tilt: 50,
};
const view = new itowns.GlobeView(map, placement);

const region = 'ap-northeast-1';
const mapName = 'SampleMap';
const apiKey = 'v1.public.xxxxx';

const mapSource = new itowns.VectorTilesSource({
    style: `https://maps.geo.${region}.amazonaws.com/maps/v0/maps/${mapName}/style-descriptor?key=${apiKey}`,
    attribution: {
        name: '©︎ 2022 HERE',
    },
});
const mapLayer = new itowns.ColorLayer('mapLayer', {
    source: mapSource,
});
view.addLayer(mapLayer);
```

#### vite.config.ts

```typescript
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      './runtimeConfig': './runtimeConfig.browser',
    },
  },
  define: {
    'window.global': {}
  },
})
```

Start local server

```bash
npm run dev
```

![img](https://memo.dayjournal.dev/images/builders-flash/202308_3d-map-library-location-service/itowns_als.png)  

<br>

## Summary
By using the API key function of Amazon Location Service, it is easier than before to build each map library. And now, Cognito authentication can be easily built using [Amplify Geo](https://docs.amplify.aws/lib/geo/getting-started/q/platform/js/) and the [Amazon Location SDK](https://docs.aws.amazon.com/location/latest/developerguide/dev-location-libraries.html). The convenience of the Amazon Location Service is improving day by day!

<br>

And for each 3D map library, support for the vector tile style adopted by the Amazon Location Service is still in its early stages and may take some time to support fully.

<br>

Nevertheless, the Amazon Location Service allows location-based applications to be built utilizing a variety of map libraries, including 2D, 2.5D, and 3D. By having a wider choice of map libraries, you can introduce the Amazon Location Service to existing applications and choose the technology you want when building a new application. I hope this example will be helpful to those building location-based applications on AWS!

<br>

Unofficially, I distribute monthly updates of Amazon Location Service.
[Monthly Amazon Location Service Updates (JPN)](https://day-journal.com/memo/tags/Monthly-Amazon-Location-Service-Updates)
[Monthly Amazon Location Service Updates (ENG)](https://dev.to/t/amazonlocationserviceupdates)

<br>

Related Articles
{% link https://dev.to/aws-heroes/amazon-location-service-and-aws-amplify-to-use-various-map-library-4mmk %}
{% link https://dev.to/aws-heroes/building-a-map-application-with-amazon-location-service-leaflet-and-aws-amplify-5gbe %}
{% link https://dev.to/aws-heroes/building-a-map-application-with-amazon-location-service-openlayers-and-aws-amplify-2f54 %}

<br>

References
[Amazon Location Service](https://aws.amazon.com/location)
[iTowns](https://www.itowns-project.org)