Skip to content

Commit

Permalink
Add support for standalone Places, Routes SDKs (#40)
Browse files Browse the repository at this point in the history 
* Bump micromatch from 4.0.5 to 4.0.8

Bumps [micromatch](https://github.com/micromatch/micromatch) from 4.0.5 to 4.0.8.
- [Release notes](https://github.com/micromatch/micromatch/releases)
- [Changelog](https://github.com/micromatch/micromatch/blob/master/CHANGELOG.md)
- [Commits](micromatch/micromatch@4.0.5...4.0.8)

---
updated-dependencies:
- dependency-name: micromatch
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>

* Bump fast-xml-parser and @aws-sdk/client-location

Bumps [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) to 4.4.1 and updates ancestor dependency [@aws-sdk/client-location](https://github.com/aws/aws-sdk-js-v3/tree/HEAD/clients/client-location). These dependencies need to be updated together.


Updates `fast-xml-parser` from 4.2.5 to 4.4.1
- [Release notes](https://github.com/NaturalIntelligence/fast-xml-parser/releases)
- [Changelog](https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/CHANGELOG.md)
- [Commits](NaturalIntelligence/fast-xml-parser@v4.2.5...v4.4.1)

Updates `@aws-sdk/client-location` from 3.359.0 to 3.649.0
- [Release notes](https://github.com/aws/aws-sdk-js-v3/releases)
- [Changelog](https://github.com/aws/aws-sdk-js-v3/blob/main/clients/client-location/CHANGELOG.md)
- [Commits](https://github.com/aws/aws-sdk-js-v3/commits/v3.649.0/clients/client-location)

---
updated-dependencies:
- dependency-name: fast-xml-parser
  dependency-type: indirect
- dependency-name: "@aws-sdk/client-location"
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <[email protected]>

* Added V2 Place API support to place-converter.

* Removed unused import.

* Removed partialFlattenList.
On further investigation, Polygon should be fully flattened, and none
of the other fields listed actually appear in supported Response types.

* Moved GeoPlaces APIs into separate files and APIs.
For the new GeoPlaces APIs, each Response type is now mapped
to a separate API. This makes the code easier to write and maintain,
and will scale better if more APIs are added over time.

* Bump rollup from 3.22.0 to 3.29.5

Bumps [rollup](https://github.com/rollup/rollup) from 3.22.0 to 3.29.5.
- [Release notes](https://github.com/rollup/rollup/releases)
- [Changelog](https://github.com/rollup/rollup/blob/master/CHANGELOG.md)
- [Commits](rollup/rollup@v3.22.0...v3.29.5)

---
updated-dependencies:
- dependency-name: rollup
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <[email protected]>

* Fixed id handling to be more MapLibre-friendly.
MapLibre expects GeoJSON Feature ids to be integers.
By placing PlaceId values in the id field, they get stripped by
MapLibre into "undefined". However, because PlaceId is a valid
Feature id value for uses other MapLibre, this change changes the
place-converter to stop stripping PlaceId from properties and leaves
the id alone for backwards compatibility. The new geoplaces-converter
has been changed to put a unique integer in the id field and to stop
stripping PlaceId from properties.

* Adds converter for V2 CalculateRoutesResponse.
This converter is more complex than the V0 converter. It exposes
options for converting leg lines, travel step lines, travel step
points, leg arrival/departure points, and span lines.
When all of these are combined in a single GeoJSON, they can be
drawn, detected, and styled differently based on the FeatureType
property added to each generated Feature.

* Updated to the newest geoplaces-client.
This API change replaces Query with QueryText.

* Fixed PR feedback.

* Fixed some README method name typos

* Added remaining V2 API support (#7)

* Added V2 route converters and changed flattenProperties default to true.
Added converters for CalculateIsolines, OptimizeWaypoints, and
SnapToRoads. Also changed all of the flattenProperties defaults for the
V2 converters to true because that's the common use case path for use
with MapLibre.

* Updated all comments to include examples of rendering the results.
Also made everything more typedoc-friendly.

* Fixed up README and comments.

* Removed unneeded comments.

* Addressed PR feedback.

* Renamed feature types based on PR feedback.

* Optimized and split the extract methods.

* Fixed README to match PR feedback changes.

* Specify browser artifacts

The UMD build should be used for browsers (and unpkg, which otherwise
references `main`, which is now CommonJS).

* Simplify unpkg URLs

* Switch to jsdelivr

* Update to the latest clients (#10)

The package names changed (now geo-<vertical>) and a property was
removed from Routes.

* Switched to public polyline release (#11)

* Switched to public polyline release.

* Switch to released polyline package.
Previous commit was relying on a locally-installed
development build of @aws-geospatial/polyline, which is why
it didn't cause any compile failures.

* Added commonjs to the datatypes rollup

* Use new public packages.
Also added a CHANGELOG.md file.

* Bump rollup from 3.22.0 to 3.29.5

Bumps [rollup](https://github.com/rollup/rollup) from 3.22.0 to 3.29.5.
- [Release notes](https://github.com/rollup/rollup/releases)
- [Changelog](https://github.com/rollup/rollup/blob/master/CHANGELOG.md)
- [Commits](rollup/rollup@v3.22.0...v3.29.5)

---
updated-dependencies:
- dependency-name: rollup
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <[email protected]>

* Fixed package-lock merge conflict.

* Deleted package-lock.json temporarily.

* Fixed up package-lock.json again

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Chris Galvan <[email protected]>
Co-authored-by: Juan Lucero <[email protected]>
Co-authored-by: Seth Fitzsimmons <[email protected]>
  • Loading branch information
@mbalfour-amzn @dependabot
@cgalvan @juaneslucero @mojodna
5 people authored Oct 30, 2024
1 parent b83b2f0 commit ae072c8
Show file tree
Hide file tree
Showing 13 changed files with 8,625 additions and 10,293 deletions.
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# 1.1.0

### ✨ Features and improvements

- Added support for new standalone Places and Routes SDKs
187 changes: 181 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ npm install @aws/amazon-location-utilities-datatypes
Importing in an HTML file for usage directly in the browser.

```html
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-datatypes@1.x/dist/amazonLocationDataConverter.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-datatypes@1"></script>
```

# Usage
Expand Down Expand Up @@ -48,10 +48,10 @@ This example uses the Amazon Location Client. The Amazon Location Client is base
Utility functions will be within `amazonLocationDataConverter`.

```html
<!-- Importing Amazon Location Client -->
<script src="https://www.unpkg.com/@aws/amazon-location-client@1.x/dist/amazonLocationClient.js"></script>
<!-- Importing the utility library from an HTML file -->
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-datatypes@1.x/dist/amazonLocationDataConverter.js"></script>
<!-- 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>
```

```javascript
Expand Down Expand Up @@ -145,11 +145,184 @@ const featureCollection = routeToFeatureCollection(response)

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

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

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

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

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

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

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

```javascript
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 is a GeometryCollection that can contain a mix of Polygons and LineStrings.
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)
```

### 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.

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

```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.
Expand All @@ -159,6 +332,8 @@ 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.
Expand Down
Loading

0 comments on commit ae072c8

Please sign in to comment.