Skip to content

Commit a732d5f

Browse files
mazyu36mazyu36
committed
docs(location): specify that Map, PlaceIndex, and RouteCalculator are 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*
1 parent 945ebfd commit a732d5f

File tree

1 file changed

+84
-102
lines changed
  • packages/@aws-cdk/aws-location-alpha

1 file changed

+84
-102
lines changed

‎packages/@aws-cdk/aws-location-alpha/README.md‎

Lines changed: 84 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -24,62 +24,6 @@ global, trusted providers Esri and HERE. With affordable data, tracking and geof
2424
capabilities, and built-in metrics for health monitoring, you can build sophisticated
2525
location-enabled applications.
2626

27-
## Map
28-
29-
The Amazon Location Service Map resource gives you access to the underlying basemap data for a map.
30-
You use the Map resource with a map rendering library to add an interactive map to your application.
31-
You can add other functionality to your map, such as markers (or pins), routes, and polygon areas, as needed for your application.
32-
33-
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).
34-
35-
To create a map, define a `Map`:
36-
37-
```ts
38-
new location.Map(this, 'Map', {
39-
mapName: 'my-map',
40-
style: location.Style.VECTOR_ESRI_NAVIGATION,
41-
customLayers: [location.CustomLayer.POI],
42-
});
43-
```
44-
45-
Use the `grant()` or `grantRendering()` method to grant the given identity permissions to perform actions
46-
on the map:
47-
48-
```ts
49-
declare const role: iam.Role;
50-
51-
const map = new location.Map(this, 'Map', {
52-
style: location.Style.VECTOR_ESRI_NAVIGATION,
53-
});
54-
map.grantRendering(role);
55-
```
56-
57-
## Place Index
58-
59-
A key function of Amazon Location Service is the ability to search the geolocation information.
60-
Amazon Location provides this functionality via the Place index resource. The place index includes
61-
which [data provider](https://docs.aws.amazon.com/location/latest/developerguide/what-is-data-provider.html)
62-
to use for the search.
63-
64-
To create a place index, define a `PlaceIndex`:
65-
66-
```ts
67-
new location.PlaceIndex(this, 'PlaceIndex', {
68-
placeIndexName: 'MyPlaceIndex', // optional, defaults to a generated name
69-
dataSource: location.DataSource.HERE, // optional, defaults to Esri
70-
});
71-
```
72-
73-
Use the `grant()` or `grantSearch()` method to grant the given identity permissions to perform actions
74-
on the place index:
75-
76-
```ts
77-
declare const role: iam.Role;
78-
79-
const placeIndex = new location.PlaceIndex(this, 'PlaceIndex');
80-
placeIndex.grantSearch(role);
81-
```
82-
8327
## Geofence Collection
8428

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

111-
## Route Calculator
112-
113-
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.
114-
115-
For more information, see [Routes](https://docs.aws.amazon.com/location/latest/developerguide/route-concepts.html).
116-
117-
To create a route calculator, define a `RouteCalculator`:
118-
119-
```ts
120-
new location.RouteCalculator(this, 'RouteCalculator', {
121-
routeCalculatorName: 'MyRouteCalculator', // optional, defaults to a generated name
122-
dataSource: location.DataSource.ESRI,
123-
});
124-
```
125-
126-
Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
127-
on the route calculator:
128-
129-
```ts
130-
declare const role: iam.Role;
131-
132-
const routeCalculator = new location.RouteCalculator(this, 'RouteCalculator', {
133-
dataSource: location.DataSource.ESRI,
134-
});
135-
routeCalculator.grantRead(role);
136-
```
137-
13855
## Tracker
13956

14057
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.
@@ -152,7 +69,7 @@ new location.Tracker(this, 'Tracker', {
15269
});
15370
```
15471

155-
Use the `grant()`, `grantUpdateDevicePositions` or `grantRead()` method to grant the given identity permissions to perform actions
72+
Use the `grant()`, `grantUpdateDevicePositions()` or `grantRead()` method to grant the given identity permissions to perform actions
15673
on the geofence collection:
15774

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

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

17087
```ts
17188
declare const geofenceCollection: location.GeofenceCollection;
@@ -180,28 +97,93 @@ const tracker = new location.Tracker(this, 'Tracker', {
18097
tracker.addGeofenceCollections(geofenceCollectionForAdd);
18198
```
18299

183-
## API key
100+
## Legacy Resources
101+
102+
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.
103+
104+
As a result, the following constructs are now considered legacy.
105+
106+
For more information, see [developer guide](https://docs.aws.amazon.com/location/latest/developerguide/what-is.html).
184107

185-
API keys are a key value that is associated with specific Amazon Location Service resources or API in your AWS account, and specific actions that you can perform on those resources.
186-
You can use an API key in your application to make unauthenticated calls to the Amazon Location APIs for those resources.
108+
### Map
187109

188-
For more information, see [Use API keys to authenticate](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html).
110+
The Amazon Location Service Map resource gives you access to the underlying basemap data for a map.
111+
You use the Map resource with a map rendering library to add an interactive map to your application.
112+
You can add other functionality to your map, such as markers (or pins), routes, and polygon areas, as needed for your application.
113+
114+
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).
189115

190-
To create an API key, define an `ApiKey`:
116+
To create a map, define a `Map`:
191117

192118
```ts
193-
new location.ApiKey(this, 'APIKeyAny', {
194-
// specify allowed actions
195-
allowMapsActions: [
196-
location.AllowMapsAction.GET_STATIC_MAP,
197-
],
198-
allowPlacesActions: [
199-
location.AllowPlacesAction.GET_PLACE,
200-
],
201-
allowRoutesActions: [
202-
location.AllowRoutesAction.CALCULATE_ISOLINES,
203-
],
119+
new location.Map(this, 'Map', {
120+
mapName: 'my-map',
121+
style: location.Style.VECTOR_ESRI_NAVIGATION,
122+
customLayers: [location.CustomLayer.POI],
204123
});
205124
```
206125

207-
> 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.
126+
Use the `grant()` or `grantRendering()` method to grant the given identity permissions to perform actions
127+
on the map:
128+
129+
```ts
130+
declare const role: iam.Role;
131+
132+
const map = new location.Map(this, 'Map', {
133+
style: location.Style.VECTOR_ESRI_NAVIGATION,
134+
});
135+
map.grantRendering(role);
136+
```
137+
138+
### Place Index
139+
140+
A key function of Amazon Location Service is the ability to search the geolocation information.
141+
Amazon Location provides this functionality via the Place index resource. The place index includes
142+
which [data provider](https://docs.aws.amazon.com/location/latest/developerguide/what-is-data-provider.html)
143+
to use for the search.
144+
145+
To create a place index, define a `PlaceIndex`:
146+
147+
```ts
148+
new location.PlaceIndex(this, 'PlaceIndex', {
149+
placeIndexName: 'MyPlaceIndex', // optional, defaults to a generated name
150+
dataSource: location.DataSource.HERE, // optional, defaults to Esri
151+
});
152+
```
153+
154+
Use the `grant()` or `grantSearch()` method to grant the given identity permissions to perform actions
155+
on the place index:
156+
157+
```ts
158+
declare const role: iam.Role;
159+
160+
const placeIndex = new location.PlaceIndex(this, 'PlaceIndex');
161+
placeIndex.grantSearch(role);
162+
```
163+
164+
### Route Calculator
165+
166+
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.
167+
168+
For more information, see [Routes](https://docs.aws.amazon.com/location/latest/developerguide/route-concepts.html).
169+
170+
To create a route calculator, define a `RouteCalculator`:
171+
172+
```ts
173+
new location.RouteCalculator(this, 'RouteCalculator', {
174+
routeCalculatorName: 'MyRouteCalculator', // optional, defaults to a generated name
175+
dataSource: location.DataSource.ESRI,
176+
});
177+
```
178+
179+
Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions
180+
on the route calculator:
181+
182+
```ts
183+
declare const role: iam.Role;
184+
185+
const routeCalculator = new location.RouteCalculator(this, 'RouteCalculator', {
186+
dataSource: location.DataSource.ESRI,
187+
});
188+
routeCalculator.grantRead(role);
189+
```

0 commit comments

Comments
 (0)