Skip to content

Latest commit

 

History

History
360 lines (256 loc) · 16.9 KB

README.md

File metadata and controls

360 lines (256 loc) · 16.9 KB
Raw

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://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-datatypes@1"></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.

<!-- Import the Amazon Location Client -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
<!-- Import the utility library -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-datatypes@1"></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.

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 = routeToFeatureCollection(response)
const response = { ... };
const featureCollection = routeToFeatureCollection(response, {
    flattenProperties: true
});

Amazon Location GeoPlaces Data Types to GeoJSON

geocodeResponseToFeatureCollection

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.

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

getPlaceResponseToFeatureCollection

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.

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

reverseGeocodeResponseToFeatureCollection

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.

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

searchNearbyResponseToFeatureCollection

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.

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

searchTextResponseToFeatureCollection

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.

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

suggestResponseToFeatureCollection

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.

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

Amazon Location GeoRoutes Data Types to GeoJSON

calculateRoutesResponseToFeatureCollection

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)
const response = { ... };
const featureCollections = calculateRoutesResponseToFeatureCollections(response)

calculateIsolinesResponseToFeatureCollection

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().

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

optimizeWaypointsResponseToFeatureCollection

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.
const response = { ... };
const featureCollection = optimizeWaypointsResponseToFeatureCollection(response)

snapToRoadsResponseToFeatureCollection

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)
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:

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.