@aws-cdk/aws-location-alpha

AWS::Location Construct Library

Version 2.274.0-alpha.0

Separate package

@aws-cdk/aws-location-alpha is not part of aws-cdk-lib — install it separately:

npm install @aws-cdk/aws-location-alpha
pip install aws-cdk.aws-location-alpha

This module is experimental (alpha): its API may change in any release, without a major version bump.

---

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

---

This module is part of the AWS Cloud Development Kit project.

Amazon Location Service lets you add location data and functionality to applications, which includes capabilities such as maps, points of interest, geocoding, routing, geofences, and tracking. Amazon Location provides location-based services (LBS) using high-quality data from global, trusted providers Esri and HERE. With affordable data, tracking and geofencing capabilities, and built-in metrics for health monitoring, you can build sophisticated location-enabled applications.

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.

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
});

# key: kms.Key


location.GeofenceCollection(self, "GeofenceCollection",
    geofence_collection_name="MyGeofenceCollection",  # optional, defaults to a generated name
    kms_key=key
)

Key key;


GeofenceCollection.Builder.create(this, "GeofenceCollection")
        .geofenceCollectionName("MyGeofenceCollection") // optional, defaults to a generated name
        .kmsKey(key)
        .build();

Key key;


new GeofenceCollection(this, "GeofenceCollection", new GeofenceCollectionProps {
    GeofenceCollectionName = "MyGeofenceCollection",  // optional, defaults to a generated name
    KmsKey = key
});

var key Key


location.NewGeofenceCollection(this, jsii.String("GeofenceCollection"), &GeofenceCollectionProps{
	GeofenceCollectionName: jsii.String("MyGeofenceCollection"),
	 // optional, defaults to a generated name
	KmsKey: key,
})

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

declare const role: iam.Role;

const geofenceCollection = new location.GeofenceCollection(this, 'GeofenceCollection', {
  geofenceCollectionName: 'MyGeofenceCollection',
});

geofenceCollection.grantRead(role);

# role: iam.Role


geofence_collection = location.GeofenceCollection(self, "GeofenceCollection",
    geofence_collection_name="MyGeofenceCollection"
)

geofence_collection.grant_read(role)

Role role;


GeofenceCollection geofenceCollection = GeofenceCollection.Builder.create(this, "GeofenceCollection")
        .geofenceCollectionName("MyGeofenceCollection")
        .build();

geofenceCollection.grantRead(role);

Role role;


var geofenceCollection = new GeofenceCollection(this, "GeofenceCollection", new GeofenceCollectionProps {
    GeofenceCollectionName = "MyGeofenceCollection"
});

geofenceCollection.GrantRead(role);

var role Role


geofenceCollection := location.NewGeofenceCollection(this, jsii.String("GeofenceCollection"), &GeofenceCollectionProps{
	GeofenceCollectionName: jsii.String("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.

To create a tracker, define a Tracker:

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
});

# key: kms.Key


location.Tracker(self, "Tracker",
    tracker_name="MyTracker",  # optional, defaults to a generated name
    kms_key=key
)

Key key;


Tracker.Builder.create(this, "Tracker")
        .trackerName("MyTracker") // optional, defaults to a generated name
        .kmsKey(key)
        .build();

Key key;


new Tracker(this, "Tracker", new TrackerProps {
    TrackerName = "MyTracker",  // optional, defaults to a generated name
    KmsKey = key
});

var key Key


location.NewTracker(this, jsii.String("Tracker"), &TrackerProps{
	TrackerName: jsii.String("MyTracker"),
	 // optional, defaults to a generated name
	KmsKey: key,
})

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

declare const role: iam.Role;

const tracker = new location.Tracker(this, 'Tracker', {
  trackerName: 'MyTracker',
});

tracker.grantRead(role);

# role: iam.Role


tracker = location.Tracker(self, "Tracker",
    tracker_name="MyTracker"
)

tracker.grant_read(role)

Role role;


Tracker tracker = Tracker.Builder.create(this, "Tracker")
        .trackerName("MyTracker")
        .build();

tracker.grantRead(role);

Role role;


var tracker = new Tracker(this, "Tracker", new TrackerProps {
    TrackerName = "MyTracker"
});

tracker.GrantRead(role);

var role Role


tracker := location.NewTracker(this, jsii.String("Tracker"), &TrackerProps{
	TrackerName: jsii.String("MyTracker"),
})

tracker.GrantRead(role)

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

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

# geofence_collection: location.GeofenceCollection
# geofence_collection_for_add: location.GeofenceCollection
# tracker: location.Tracker


tracker = location.Tracker(self, "Tracker",
    tracker_name="MyTracker",
    geofence_collections=[geofence_collection]
)

tracker.add_geofence_collections(geofence_collection_for_add)

GeofenceCollection geofenceCollection;
GeofenceCollection geofenceCollectionForAdd;
Tracker tracker;


Tracker tracker = Tracker.Builder.create(this, "Tracker")
        .trackerName("MyTracker")
        .geofenceCollections(List.of(geofenceCollection))
        .build();

tracker.addGeofenceCollections(geofenceCollectionForAdd);

GeofenceCollection geofenceCollection;
GeofenceCollection geofenceCollectionForAdd;
Tracker tracker;


var tracker = new Tracker(this, "Tracker", new TrackerProps {
    TrackerName = "MyTracker",
    GeofenceCollections = new [] { geofenceCollection }
});

tracker.AddGeofenceCollections(geofenceCollectionForAdd);

var geofenceCollection GeofenceCollection
var geofenceCollectionForAdd GeofenceCollection
var tracker Tracker


tracker := location.NewTracker(this, jsii.String("Tracker"), &TrackerProps{
	TrackerName: jsii.String("MyTracker"),
	GeofenceCollections: []IGeofenceCollection{
		geofenceCollection,
	},
})

tracker.AddGeofenceCollections(geofenceCollectionForAdd)

API key

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. You can use an API key in your application to make unauthenticated calls to the Amazon Location APIs for those resources.

For more information, see Use API keys to authenticate.

To create an API key, define an ApiKey:

new location.ApiKey(this, 'APIKeyAny', {
  // specify allowed actions
  allowMapsActions: [
    location.AllowMapsAction.GET_STATIC_MAP,
  ],
  allowPlacesActions: [
    location.AllowPlacesAction.GET_PLACE,
  ],
  allowRoutesActions: [
    location.AllowRoutesAction.CALCULATE_ISOLINES,
  ],
});

location.ApiKey(self, "APIKeyAny",
    # specify allowed actions
    allow_maps_actions=[location.AllowMapsAction.GET_STATIC_MAP
    ],
    allow_places_actions=[location.AllowPlacesAction.GET_PLACE
    ],
    allow_routes_actions=[location.AllowRoutesAction.CALCULATE_ISOLINES
    ]
)

ApiKey.Builder.create(this, "APIKeyAny")
        // specify allowed actions
        .allowMapsActions(List.of(AllowMapsAction.GET_STATIC_MAP))
        .allowPlacesActions(List.of(AllowPlacesAction.GET_PLACE))
        .allowRoutesActions(List.of(AllowRoutesAction.CALCULATE_ISOLINES))
        .build();

new ApiKey(this, "APIKeyAny", new ApiKeyProps {
    // specify allowed actions
    AllowMapsActions = new [] { AllowMapsAction.GET_STATIC_MAP },
    AllowPlacesActions = new [] { AllowPlacesAction.GET_PLACE },
    AllowRoutesActions = new [] { AllowRoutesAction.CALCULATE_ISOLINES }
});

location.NewApiKey(this, jsii.String("APIKeyAny"), &ApiKeyProps{
	// specify allowed actions
	AllowMapsActions: []AllowMapsAction{
		location.AllowMapsAction_GET_STATIC_MAP,
	},
	AllowPlacesActions: []AllowPlacesAction{
		location.AllowPlacesAction_GET_PLACE,
	},
	AllowRoutesActions: []AllowRoutesAction{
		location.AllowRoutesAction_CALCULATE_ISOLINES,
	},
})

Note: ApiKey construct only supports Enhanced Places, Routes, 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. 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.

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.

To create a map, define a Map:

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

location.Map(self, "Map",
    map_name="my-map",
    style=location.Style.VECTOR_ESRI_NAVIGATION,
    custom_layers=[location.CustomLayer.POI]
)

Map.Builder.create(this, "Map")
        .mapName("my-map")
        .style(Style.VECTOR_ESRI_NAVIGATION)
        .customLayers(List.of(CustomLayer.POI))
        .build();

new Map(this, "Map", new MapProps {
    MapName = "my-map",
    Style = Style.VECTOR_ESRI_NAVIGATION,
    CustomLayers = new [] { CustomLayer.POI }
});

location.NewMap(this, jsii.String("Map"), &MapProps{
	MapName: jsii.String("my-map"),
	Style: location.Style_VECTOR_ESRI_NAVIGATION,
	CustomLayers: []pOI{
		location.CustomLayer_*pOI,
	},
})

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

declare const role: iam.Role;

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

# role: iam.Role


map = location.Map(self, "Map",
    style=location.Style.VECTOR_ESRI_NAVIGATION
)
map.grant_rendering(role)

Role role;


Map map = Map.Builder.create(this, "Map")
        .style(Style.VECTOR_ESRI_NAVIGATION)
        .build();
map.grantRendering(role);

Role role;


var map = new Map(this, "Map", new MapProps {
    Style = Style.VECTOR_ESRI_NAVIGATION
});
map.GrantRendering(role);

var role Role


map := location.NewMap(this, jsii.String("Map"), &MapProps{
	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 to use for the search.

To create a place index, define a PlaceIndex:

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

location.PlaceIndex(self, "PlaceIndex",
    place_index_name="MyPlaceIndex",  # optional, defaults to a generated name
    data_source=location.DataSource.HERE
)

PlaceIndex.Builder.create(this, "PlaceIndex")
        .placeIndexName("MyPlaceIndex") // optional, defaults to a generated name
        .dataSource(DataSource.HERE)
        .build();

new PlaceIndex(this, "PlaceIndex", new PlaceIndexProps {
    PlaceIndexName = "MyPlaceIndex",  // optional, defaults to a generated name
    DataSource = DataSource.HERE
});

location.NewPlaceIndex(this, jsii.String("PlaceIndex"), &PlaceIndexProps{
	PlaceIndexName: jsii.String("MyPlaceIndex"),
	 // optional, defaults to a generated name
	DataSource: location.DataSource_HERE,
})

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

declare const role: iam.Role;

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

# role: iam.Role


place_index = location.PlaceIndex(self, "PlaceIndex")
place_index.grant_search(role)

Role role;


PlaceIndex placeIndex = new PlaceIndex(this, "PlaceIndex");
placeIndex.grantSearch(role);

Role role;


var placeIndex = new PlaceIndex(this, "PlaceIndex");
placeIndex.GrantSearch(role);

var role Role


placeIndex := location.NewPlaceIndex(this, jsii.String("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.

To create a route calculator, define a RouteCalculator:

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

location.RouteCalculator(self, "RouteCalculator",
    route_calculator_name="MyRouteCalculator",  # optional, defaults to a generated name
    data_source=location.DataSource.ESRI
)

RouteCalculator.Builder.create(this, "RouteCalculator")
        .routeCalculatorName("MyRouteCalculator") // optional, defaults to a generated name
        .dataSource(DataSource.ESRI)
        .build();

new RouteCalculator(this, "RouteCalculator", new RouteCalculatorProps {
    RouteCalculatorName = "MyRouteCalculator",  // optional, defaults to a generated name
    DataSource = DataSource.ESRI
});

location.NewRouteCalculator(this, jsii.String("RouteCalculator"), &RouteCalculatorProps{
	RouteCalculatorName: jsii.String("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:

declare const role: iam.Role;

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

# role: iam.Role


route_calculator = location.RouteCalculator(self, "RouteCalculator",
    data_source=location.DataSource.ESRI
)
route_calculator.grant_read(role)

Role role;


RouteCalculator routeCalculator = RouteCalculator.Builder.create(this, "RouteCalculator")
        .dataSource(DataSource.ESRI)
        .build();
routeCalculator.grantRead(role);

Role role;


var routeCalculator = new RouteCalculator(this, "RouteCalculator", new RouteCalculatorProps {
    DataSource = DataSource.ESRI
});
routeCalculator.GrantRead(role);

var role Role


routeCalculator := location.NewRouteCalculator(this, jsii.String("RouteCalculator"), &RouteCalculatorProps{
	DataSource: location.DataSource_ESRI,
})
routeCalculator.GrantRead(role)

Types

Name	Kind	Summary
ApiKey	Construct (L2)	An API Key.
GeofenceCollection	Construct (L2)	A Geofence Collection.
Map	Construct (L2)	The Amazon Location Service Map.
PlaceIndex	Construct (L2)	A Place Index.
RouteCalculator	Construct (L2)	A Route Calculator.
Tracker	Construct (L2)	A Tracker.
AllowMapsAction	Enum	Actions for Maps that an API key resource grants permissions to perform.
AllowPlacesAction	Enum	Actions for Places that an API key resource grants permissions to perform.
AllowRoutesAction	Enum	Actions for Routes that an API key resource grants permissions to perform.
ApiKeyProps	Struct	Properties for an API Key.
CustomLayer	Enum	An additional layer you can enable for a map style.
DataSource	Enum	Data source for a place index.
GeofenceCollectionProps	Struct	Properties for a geofence collection.
IApiKey	Interface	An API Key.
IGeofenceCollection	Interface	A Geofence Collection.
IMap	Interface	Represents the Amazon Location Service Map.
IntendedUse	Enum	Intend use for the results of an operation.
IPlaceIndex	Interface	A Place Index.
IRouteCalculator	Interface	A Route Calculator.
ITracker	Interface	A Tracker.
MapProps	Struct	Properties for the Amazon Location Service Map.
PlaceIndexProps	Struct	Properties for a place index.
PoliticalView	Enum	The map political view.
PositionFiltering	Enum	The position filtering for the tracker resource.
RouteCalculatorProps	Struct	Properties for a route calculator.
Style	Enum	The map style selected from an available data provider.
TrackerProps	Struct	Properties for a tracker.