Skip to content

Commit

Permalink
docs(location): specify that Map, PlaceIndex, and RouteCalculator are…
Browse files Browse the repository at this point in the history 
… now legacy in README (#32871)

Closes #32722.

Amazon Location Service launches Enhanced Places, Routes, and Maps on Nov 8, 2024 ([Ref](https://aws.amazon.com/about-aws/whats-new/2024/11/amazon-location-service-enhanced-places-routes-maps/?nc1=h_ls)).

New APIs for Maps, Places and Routes are launched and account-bound resources are no longer required.

Therefore, I think it’s better to mention in the README that the constructs related to these are considered legacy.

* Add a section for legacy resources in the README.
* Move the descriptions related to Map, PlaceIndex, and RouteCalculator to that section.

None

None

- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
  • Loading branch information
@mazyu36
mazyu36 committed Jan 28, 2025
1 parent 05a9926 commit aa0019d
Showing 1 changed file with 93 additions and 85 deletions.
178 changes: 93 additions & 85 deletions packages/@aws-cdk/aws-location-alpha/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,62 +24,6 @@ global, trusted providers Esri and HERE. With affordable data, tracking and geof
capabilities, and built-in metrics for health monitoring, you can build sophisticated
location-enabled applications.

## Map

The Amazon Location Service Map resource gives you access to the underlying basemap data for a map.
You use the Map resource with a map rendering library to add an interactive map to your application.
You can add other functionality to your map, such as markers (or pins), routes, and polygon areas, as needed for your application.

For information about how to use map resources in practice, see [Using Amazon Location Maps in your application](https://docs.aws.amazon.com/location/latest/developerguide/using-maps.html).

To create a map, define a `Map`:

```ts
new location.Map(this, 'Map', {
mapName: 'my-map',
style: location.Style.VECTOR_ESRI_NAVIGATION,
customLayers: [location.CustomLayer.POI],
});
```

Use the `grant()` or `grantRendering()` method to grant the given identity permissions to perform actions
on the map:

```ts
declare const role: iam.Role;

const map = new location.Map(this, 'Map', {
style: location.Style.VECTOR_ESRI_NAVIGATION,
});
map.grantRendering(role);
```

## Place Index

A key function of Amazon Location Service is the ability to search the geolocation information.
Amazon Location provides this functionality via the Place index resource. The place index includes
which [data provider](https://docs.aws.amazon.com/location/latest/developerguide/what-is-data-provider.html)
to use for the search.

To create a place index, define a `PlaceIndex`:

```ts
new location.PlaceIndex(this, 'PlaceIndex', {
placeIndexName: 'MyPlaceIndex', // optional, defaults to a generated name
dataSource: location.DataSource.HERE, // optional, defaults to Esri
});
```

Use the `grant()` or `grantSearch()` method to grant the given identity permissions to perform actions
on the place index:

```ts
declare const role: iam.Role;

const placeIndex = new location.PlaceIndex(this, 'PlaceIndex');
placeIndex.grantSearch(role);
```

## Geofence Collection

Geofence collection resources allow you to store and manage geofences—virtual boundaries on a map.
Expand Down Expand Up @@ -108,33 +52,6 @@ const geofenceCollection = new location.GeofenceCollection(this, 'GeofenceCollec
geofenceCollection.grantRead(role);
```

## Route Calculator

Route calculator resources allow you to find routes and estimate travel time based on up-to-date road network and live traffic information from your chosen data provider.

For more information, see [Routes](https://docs.aws.amazon.com/location/latest/developerguide/route-concepts.html).

To create a route calculator, define a `RouteCalculator`:

```ts
new location.RouteCalculator(this, 'RouteCalculator', {
routeCalculatorName: 'MyRouteCalculator', // optional, defaults to a generated name
dataSource: location.DataSource.ESRI,
});
```

Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
on the route calculator:

```ts
declare const role: iam.Role;

const routeCalculator = new location.RouteCalculator(this, 'RouteCalculator', {
dataSource: location.DataSource.ESRI,
});
routeCalculator.grantRead(role);
```

## Tracker

A tracker stores position updates for a collection of devices. The tracker can be used to query the devices' current location or location history. It stores the updates, but reduces storage space and visual noise by filtering the locations before storing them.
Expand All @@ -152,7 +69,7 @@ new location.Tracker(this, 'Tracker', {
});
```

Use the `grant()`, `grantUpdateDevicePositions` or `grantRead()` method to grant the given identity permissions to perform actions
Use the `grant()`, `grantUpdateDevicePositions()` or `grantRead()` method to grant the given identity permissions to perform actions
on the geofence collection:

```ts
Expand All @@ -165,7 +82,7 @@ const tracker = new location.Tracker(this, 'Tracker', {
tracker.grantRead(role);
```

If you want to associate a tracker with geofence collections, define a `geofenceCollections` property or use `addGeofenceCollections` method.
If you want to associate a tracker with geofence collections, define a `geofenceCollections` property or use the `addGeofenceCollections()` method.

```ts
declare const geofenceCollection: location.GeofenceCollection;
Expand Down Expand Up @@ -205,3 +122,94 @@ new location.ApiKey(this, 'APIKeyAny', {
```

> Note: `ApiKey` construct only supports [Enhanced Places, Routes, and Maps](https://aws.amazon.com/blogs/aws/announcing-new-apis-for-amazon-location-service-routes-places-and-maps/) This API key grants access to AWS-managed Places, Routes, and Maps.
## Legacy Resources

AWS has released new [Enhanced Places, Routes, and Maps](https://aws.amazon.com/about-aws/whats-new/2024/11/amazon-location-service-enhanced-places-routes-maps/?nc1=h_ls). Since these use AWS-managed resources, users no longer need to create Maps, Places, and Routes resources themselves.

As a result, the following constructs are now considered legacy.

For more information, see [developer guide](https://docs.aws.amazon.com/location/latest/developerguide/what-is.html).

### Map

The Amazon Location Service Map resource gives you access to the underlying basemap data for a map.
You use the Map resource with a map rendering library to add an interactive map to your application.
You can add other functionality to your map, such as markers (or pins), routes, and polygon areas, as needed for your application.

For information about how to use map resources in practice, see [Using Amazon Location Maps in your application](https://docs.aws.amazon.com/location/latest/developerguide/using-maps.html).

To create a map, define a `Map`:

```ts
new location.Map(this, 'Map', {
mapName: 'my-map',
style: location.Style.VECTOR_ESRI_NAVIGATION,
customLayers: [location.CustomLayer.POI],
});
```

Use the `grant()` or `grantRendering()` method to grant the given identity permissions to perform actions
on the map:

```ts
declare const role: iam.Role;

const map = new location.Map(this, 'Map', {
style: location.Style.VECTOR_ESRI_NAVIGATION,
});
map.grantRendering(role);
```

### Place Index

A key function of Amazon Location Service is the ability to search the geolocation information.
Amazon Location provides this functionality via the Place index resource. The place index includes
which [data provider](https://docs.aws.amazon.com/location/latest/developerguide/what-is-data-provider.html)
to use for the search.

To create a place index, define a `PlaceIndex`:

```ts
new location.PlaceIndex(this, 'PlaceIndex', {
placeIndexName: 'MyPlaceIndex', // optional, defaults to a generated name
dataSource: location.DataSource.HERE, // optional, defaults to Esri
});
```

Use the `grant()` or `grantSearch()` method to grant the given identity permissions to perform actions
on the place index:

```ts
declare const role: iam.Role;

const placeIndex = new location.PlaceIndex(this, 'PlaceIndex');
placeIndex.grantSearch(role);
```

### Route Calculator

Route calculator resources allow you to find routes and estimate travel time based on up-to-date road network and live traffic information from your chosen data provider.

For more information, see [Routes](https://docs.aws.amazon.com/location/latest/developerguide/route-concepts.html).

To create a route calculator, define a `RouteCalculator`:

```ts
new location.RouteCalculator(this, 'RouteCalculator', {
routeCalculatorName: 'MyRouteCalculator', // optional, defaults to a generated name
dataSource: location.DataSource.ESRI,
});
```

Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
on the route calculator:

```ts
declare const role: iam.Role;

const routeCalculator = new location.RouteCalculator(this, 'RouteCalculator', {
dataSource: location.DataSource.ESRI,
});
routeCalculator.grantRead(role);
```

0 comments on commit aa0019d

Please sign in to comment.