docs(location): specify that Map, PlaceIndex, and RouteCalculator are…

… now legacy in README (#32871) ### Issue # (if applicable) Closes #32722. ### Reason for this change 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. ### Description of changes * Add a section for legacy resources in the README. * Move the descriptions related to Map, PlaceIndex, and RouteCalculator to that section. ### Describe any new or updated permissions being added None ### Description of how you validated changes None ### Checklist - [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*
aws · Jan 28, 2025 · 69b25da · 69b25da
1 parent c710e70
commit 69b25da
Showing 1 changed file with 84 additions and 76 deletions.
diff --git a/packages/@aws-cdk/aws-location-alpha/README.md b/packages/@aws-cdk/aws-location-alpha/README.md
@@ -24,7 +24,88 @@ 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
+## Geofence Collection
+
+Geofence collection resources allow you to store and manage geofences—virtual boundaries on a map.
+You can evaluate locations against a geofence collection resource and get notifications when the location
+update crosses the boundary of any of the geofences in the geofence collection.
+
+```ts
+declare const key: kms.Key;
+
+new location.GeofenceCollection(this, 'GeofenceCollection', {
+  geofenceCollectionName: 'MyGeofenceCollection', // optional, defaults to a generated name
+  kmsKey: key, // optional, defaults to use an AWS managed key
+});
+```
+
+Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
+on the geofence collection:
+
+```ts
+declare const role: iam.Role;
+
+const geofenceCollection = new location.GeofenceCollection(this, 'GeofenceCollection', {
+  geofenceCollectionName: 'MyGeofenceCollection',
+});
+
+geofenceCollection.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.
+
+For more information, see [Trackers](https://docs.aws.amazon.com/location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview).
+
+To create a tracker, define a `Tracker`:
+
+```ts
+declare const key: kms.Key;
+
+new location.Tracker(this, 'Tracker', {
+  trackerName: 'MyTracker', // optional, defaults to a generated name
+  kmsKey: key, // optional, defaults to use an AWS managed key
+});
+```
+
+Use the `grant()`, `grantUpdateDevicePositions()` or `grantRead()` method to grant the given identity permissions to perform actions
+on the geofence collection:
+
+```ts
+declare const role: iam.Role;
+
+const tracker = new location.Tracker(this, 'Tracker', {
+  trackerName: 'MyTracker',
+});
+
+tracker.grantRead(role);
+```
+
+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;
+declare const geofenceCollectionForAdd: location.GeofenceCollection;
+declare const tracker: location.Tracker;
+
+const tracker = new location.Tracker(this, 'Tracker', {
+  trackerName: 'MyTracker',
+  geofenceCollections: [geofenceCollection],
+});
+
+tracker.addGeofenceCollections(geofenceCollectionForAdd);
+```
+
+## 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.
@@ -54,7 +135,7 @@ const map = new location.Map(this, 'Map', {
 map.grantRendering(role);
 ```
 
-## Place Index
+### 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
@@ -80,35 +161,7 @@ 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.
-You can evaluate locations against a geofence collection resource and get notifications when the location
-update crosses the boundary of any of the geofences in the geofence collection.
-
-```ts
-declare const key: kms.Key;
-
-new location.GeofenceCollection(this, 'GeofenceCollection', {
-  geofenceCollectionName: 'MyGeofenceCollection', // optional, defaults to a generated name
-  kmsKey: key, // optional, defaults to use an AWS managed key
-});
-```
-
-Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
-on the geofence collection:
-
-```ts
-declare const role: iam.Role;
-
-const geofenceCollection = new location.GeofenceCollection(this, 'GeofenceCollection', {
-  geofenceCollectionName: 'MyGeofenceCollection',
-});
-
-geofenceCollection.grantRead(role);
-```
-
-## Route Calculator
+### 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.
 
@@ -134,48 +187,3 @@ const routeCalculator = new location.RouteCalculator(this, 'RouteCalculator', {
 });
 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.
-
-For more information, see [Trackers](https://docs.aws.amazon.com/location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview).
-
-To create a tracker, define a `Tracker`:
-
-```ts
-declare const key: kms.Key;
-
-new location.Tracker(this, 'Tracker', {
-  trackerName: 'MyTracker', // optional, defaults to a generated name
-  kmsKey: key, // optional, defaults to use an AWS managed key
-});
-```
-
-Use the `grant()`, `grantUpdateDevicePositions` or `grantRead()` method to grant the given identity permissions to perform actions
-on the geofence collection:
-
-```ts
-declare const role: iam.Role;
-
-const tracker = new location.Tracker(this, 'Tracker', {
-  trackerName: 'MyTracker',
-});
-
-tracker.grantRead(role);
-```
-
-If you want to associate a tracker with geofence collections, define a `geofenceCollections` property or use `addGeofenceCollections` method.
-
-```ts
-declare const geofenceCollection: location.GeofenceCollection;
-declare const geofenceCollectionForAdd: location.GeofenceCollection;
-declare const tracker: location.Tracker;
-
-const tracker = new location.Tracker(this, 'Tracker', {
-  trackerName: 'MyTracker',
-  geofenceCollections: [geofenceCollection],
-});
-
-tracker.addGeofenceCollections(geofenceCollectionForAdd);
-```