Amazon Location Utilities - Data Types for JavaScript

Utilities to translate geospatial data types used by Amazon Location Service from / to well-known geospatial data types such as GeoJSON.

Installation

Install this library from NPM for usage with modules:

npm install @aws/amazon-location-utilities-datatypes

Importing in an HTML file for usage directly in the browser.

<script src="https://www.unpkg.com/@aws/[email protected]/dist/amazonLocationDataConverter.js"></script>

Usage

Import the library and call the utility functions in the top-level namespace as needed. You can find more details about these functions in the Documentation section.

The examples below show how you can translate an Amazon Location SearchPlaceIndexForText response from the AWS JavaScript SDK to a GeoJSON FeatureCollection:

Usage with modules

This example uses the AWS SDK for JavaScript V3.

// Importing AWS JavaScript SDK V3
import { LocationClient, SearchPlaceIndexForTextCommand } from "@aws-sdk/client-location";
// Importing the utility function
import { placeToFeatureCollection } from '@aws/amazon-location-utilities-datatypes'

const client = new LocationClient(config);
const input = { ... };
const command = new SearchPlaceIndexForTextCommand(input);
const response = await client.send(command);

// Calling this utility function to convert the response to GeoJSON
const featureCollection = placeToFeatureCollection(response);

Usage with the browser

This example uses the Amazon Location Client. The Amazon Location Client is based on the AWS SDK for JavaScript V3, which allows the use of making calls to Amazon Location through the script added into the HTML file.

Utility functions will be within amazonLocationDataConverter.

<!-- Importing Amazon Location Client -->
<script src="https://www.unpkg.com/@aws/[email protected]/dist/amazonLocationClient.js"></script>
<!-- Importing the utility library from an HTML file -->
<script src="https://www.unpkg.com/@aws/[email protected]/dist/amazonLocationDataConverter.js"></script>

const client = new amazonLocationClient.LocationClient(config);
const input = { ... };
const command = new amazonLocationClient.SearchPlaceIndexForTextCommand(input);
const response = await client.send(command);

// Calling this utility function to convert the response to GeoJSON
const featureCollection = amazonLocationDataConverter.placeToFeatureCollection(response);

Documentation

Detailed documentation can be found under /docs/index.html after generating it by running:

npm run typedoc

GeoJSON to Amazon Location Data Types

featureCollectionToGeofence

Converts a GeoJSON FeatureCollection with Polygon Features to an array of BatchPutGeofenceRequestEntry, so the result can be used to assemble the request to BatchPutGeofence.

const featureCollection = { ... };
const request = {
  CollectionName: "<Geofence Collection Name>",
  Entries: featureCollectionToGeofence(featureCollection),
};

Amazon Location Data Types to GeoJSON

devicePositionsToFeatureCollection

Converts tracker responses to a FeatureCollection with Point Features. It converts:

1. GetDevicePositionResponse to a FeatureCollection with a single feature.
2. BatchGetDevicePositionResponse, GetDevicePositionHistoryResponse, ListDevicePositionsResponse to a FeatureCollection with features corresponding to the entries in the response.

const response = { ... };
const featureCollection = devicePositionsToFeatureCollection(response)

geofencesToFeatureCollection

Converts a list of geofences to FeatureCollection with Polygon Features. It can convert geofences both in the response and the request, so it can also help preview geofences on the map before uploading with PutGeofence or BatchPutGeofence. It converts:

1. A Polygon Geofence to a Feature with such Polygon
2. A Circle Geofence to a Feature with approximated Polygon with Center and Radius properties.

const response = { ... };
const featureCollection = geofencesToFeatureCollection(response)

placeToFeatureCollection

Converts places search responses to a FeatureCollection with Point Features. It converts:

1. GetPlaceResponse to a FeatureCollection with a single feature.
2. SearchPlaceIndexForPositionResponse, SearchPlaceIndexForTextResponse to a FeatureCollection with features corresponding to the entries in the response.
3. The flattenProperties option will flatten the JSON response in properties.This option is mainly used when retrieving "MapLibre GL JS" attributes.

const response = { ... };
const featureCollection = placeToFeatureCollection(response)

const response = { ... };
const featureCollection = placeToFeatureCollection(response, {
    flattenProperties: true
});

routeToFeatureCollection

Converts a route to a GeoJSON FeatureCollection with a single MultiLineString Feature. Each LineString entry of the MultiLineString represents a leg of the route.

const response = { ... };
const featureCollection = routeToFeatureCollection(response)

Error Handling

If the data provided to the utility functions are invalid, the entries in the data will be skipped.

Examples:

• A FeatureCollection containing a Feature of a non-polygon type when calling featureCollectionToGeofence will result in a set of geofence entries that do not contain that Feature.
• An input to devicePositionsToFeatureCollection with an device position entry that does not contain the coordinates of the device will result in a FeatureCollection with that device position entry skipped.

Getting Help

The best way to interact with our team is through GitHub. You can open an issue and choose from one of our templates for bug reports, feature requests or guidance. If you have a support plan with AWS Support, you can also create a new support case.

Please make sure to check out our resources too before opening an issue:

• Our Changelog for recent changes.

Contributing

We welcome community contributions and pull requests. See CONTRIBUTING.md for information on how to set up a development environment and submit code.

License

Amazon Location Utilities - Data Types for JavaScript is distributed under the Apache License, Version 2.0, see LICENSE.txt and NOTICE.txt for more information.