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:

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

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

`html

`

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:

$3

This example uses the AWS SDK for JavaScript V3.

`javascript
// 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);
`

$3

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.

`html




`

`javascript
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:

`shell
npm run typedoc
`

GeoJSON to Amazon Location Data Types

$3

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

`javascript
const featureCollection = { ... };
const request = {
CollectionName: "",
Entries: featureCollectionToGeofence(featureCollection),
};
`

Amazon Location Data Types to GeoJSON

$3

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.

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

$3

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.

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

$3

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.

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

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

$3

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

The flattenProperties option will flatten the JSON response in properties.This option is mainly used when retrieving "MapLibre GL JS" attributes.

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

`javascript
const response = { ... };
const featureCollection = routeToFeatureCollection(response, {
flattenProperties: true
});
`

Amazon Location GeoPlaces Data Types to GeoJSON

$3

Converts a Geocode response from the standalone Places SDK to a FeatureCollection with Point
Features. Only result items with location information will appear in the FeatureCollection.
The flattenProperties option will flatten the nested response data into a flat properties list.
This option is enabled by default, as it makes the data easier to use from within MapLibre expressions.

`javascript
const response = { ... };
const featureCollection = geocodeResponseToFeatureCollection(response)
`

$3

Converts a GetPlace response from the standalone Places SDK to a FeatureCollection with a Point
Feature. If the response has no location information, an empty FeatureCollection will be returned.
The flattenProperties option will flatten the nested response data into a flat properties list.
This option is enabled by default, as it makes the data easier to use from within MapLibre expressions.

`javascript
const response = { ... };
const featureCollection = getPlaceResponseToFeatureCollection(response)
`

$3

Converts a ReverseGeocode response from the standalone Places SDK to a FeatureCollection with Point
Features. Only result items with location information will appear in the FeatureCollection.
The flattenProperties option will flatten the nested response data into a flat properties list.
This option is enabled by default, as it makes the data easier to use from within MapLibre expressions.

`javascript
const response = { ... };
const featureCollection = reverseGeocodeResponseToFeatureCollection(response)
`

$3

Converts a SearchNearby response from the standalone Places SDK to a FeatureCollection with Point
Features. Only result items with location information will appear in the FeatureCollection.
The flattenProperties option will flatten the nested response data into a flat properties list.
This option is enabled by default, as it makes the data easier to use from within MapLibre expressions.

`javascript
const response = { ... };
const featureCollection = searchNearbyResponseToFeatureCollection(response)
`

$3

Converts a SearchText response from the standalone Places SDK to a FeatureCollection with Point
Features. Only result items with location information will appear in the FeatureCollection.
The flattenProperties option will flatten the nested response data into a flat properties list.
This option is enabled by default, as it makes the data easier to use from within MapLibre expressions.

`javascript
const response = { ... };
const featureCollection = searchTextResponseToFeatureCollection(response)
`

$3

Converts a Suggest response from the standalone Places SDK to a FeatureCollection with Point
Features. Only result items with location information will appear in the FeatureCollection.
The flattenProperties option will flatten the nested response data into a flat properties list.
This option is enabled by default, as it makes the data easier to use from within MapLibre expressions.

`javascript
const response = { ... };
const featureCollection = suggestResponseToFeatureCollection(response)
`

Amazon Location GeoRoutes Data Types to GeoJSON

$3

This converts a CalculateRoutesResponse from the standalone Routes SDK to an array of GeoJSON FeatureCollections, one for each route in the
response. Route responses contain multiple different types of geometry in the response, so the conversion is
configurable to choose which features should be in the resulting GeoJSON. Each GeoJSON Feature contains properties
from that portion of the response along with any child arrays/structures. It will not contain properties from any
parent structures. So for example, with Route->Leg->TravelSteps, a converted Leg feature will contain properties for
everything on Leg and everything in TravelSteps, but it won't contain any properties from Route.

Each Feature contains a FeatureType property that can be used to distinguish between the types of features if
multiple are requested during the conversion:

- Leg: A travel leg of the route. (LineString)
- Span: A span within a travel leg. (LineString)
- TravelStepGeometry: A travel step line within a travel leg. (LineString)
- TravelStepStartPosition: The start position of a travel step within a travel leg. (Point)
- Arrival: The arrival position of a travel leg. (Point)
- Departure: The departure position of a travel leg. (Point)

Each FeatureCollection may contain a mixture of LineString and Point features, depending on the conversion options
provided.

Any feature that is missing its geometry in the response or has invalid geometry will throw an Error().

The API optionally accepts the following conversion flags:

- flattenProperties: flatten nested properties in the response (default: true)
- includeLegs: include the Leg features (default: true)
- includeSpans: include the Span features (default: false)
- includeTravelStepGeometry: include the TravelStepGeometry features (default: false)
- includeTravelStepStartPositions: include the TravelStepStartPosition features (default: false)
- includeLegArrivalDeparturePositions: include the Arrival and Departure features (default: false)

`javascript
const response = { ... };
const featureCollections = calculateRoutesResponseToFeatureCollections(response)
`

$3

This converts a CalculateIsolineResponse from the standalone Routes SDK to a GeoJSON
FeatureCollection which contains one Feature for each isoline in the response. Isolines can contain
both polygons for isoline regions and lines for connectors between regions (such as ferry travel),
so each Feature contains either a GeometryCollection with a mix of Polygons and LineStrings or a
single Polygon. The flattenProperties option will flatten the nested response data into a flat
properties list. This option is enabled by default, as it makes the data easier to use from within
MapLibre expressions.

Any feature that is missing its geometry in the response or has invalid geometry will throw an Error().

`javascript
const response = { ... };
const featureCollection = calculateIsolinesResponseToFeatureCollection(response)
`

$3

This converts an OptimizeWaypointsResponse from the standalone Routes SDK to a GeoJSON FeatureCollection which contains one Feature for each
waypoint in the response. The response can contain either impeding waypoints or optimized waypoints.
The flattenProperties option will flatten the nested response data into a flat properties list.
This option is enabled by default, as it makes the data easier to use from within MapLibre expressions.

Each Feature contains a FeatureType property that can be used to distinguish between the types of features:

- ImpedingWaypoint: A waypoint that impedes the optimization request.
- OptimizedWaypoint: An optimized waypoint in a successful optimization request.

`javascript
const response = { ... };
const featureCollection = optimizeWaypointsResponseToFeatureCollection(response)
`

$3

This converts a SnapToRoadsResponse from the standalone Routes SDK to a GeoJSON FeatureCollection. The FeatureCollection may optionally contain any
combination of the snapped route geometry, the original trace points, the snapped trace points, and lines that
connect the original trace points to their snapped trace points.

Each Feature contains a FeatureType property that can be used to distinguish between the types of features if
multiple are requested during the conversion:

- SnappedGeometry: The snapped route geometry. (LineString)
- SnappedTracePointOriginalPosition: The original submitted trace point. (Point)
- SnappedTracePointSnappedPosition: The snapped trace point. (Point)
- OriginalToSnappedPositionLine: A line from the original trace point to the corresponding snapped trace point. (LineString)

The API optionally accepts the following conversion flags:

- flattenProperties: flatten nested properties in the response (default: true)
- includeSnappedGeometry: include the snapped route geometry features (default: true)
- includeSnappedTracePointOriginalPositions: include the original trace point features (default: false)
- includeSnappedTracePointSnappedPositions: include the snapped trace point features (default: false)
- includeOriginalToSnappedPositionLines: include the trace point connector line features (default: false)

`javascript
const response = { ... };
const featureCollection = snapToRoadsResponseToFeatureCollection(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.

The GeoRoutes converters will additionally throw an Error() if the geometry in the passed-in response is invalid.

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.