AWS.Location reference

ApiKey

Source: src/AWS/Location/ApiKey.ts

An Amazon Location Service API key. API keys authorize unsigned requests (e.g. map tiles rendered directly in a browser) to a restricted set of Location actions and resources. The key name is immutable; restrictions, description, and expiry can be updated in place.

The key attribute is the secret key value (v1.public.…) clients pass as the key query parameter; it is wrapped in Redacted.

Availability: Amazon Location classic (V1) is closed to newer AWS accounts — geo:CreateKey is rejected service-side with an AccessDeniedException regardless of IAM policy. Accounts onboarded to Location before the V2 split can create keys normally.

ApiKey: Creating API Keys

Map-Rendering Key for Browsers

import * as Location from "alchemy/AWS/Location";

const map = yield* Location.Map("SiteMap", {
  configuration: { style: "VectorEsriStreets" },
});

const key = yield* Location.ApiKey("SiteMapKey", {
  restrictions: {
    allowActions: ["geo:GetMap*"],
    allowResources: [map.mapArn],
  },
});
// Redacted.value(key.key) → "v1.public.…" — append as ?key=… to tile URLs

Key with Referer Restrictions and Expiry

const key = yield* Location.ApiKey("WebKey", {
  restrictions: {
    allowActions: ["geo:GetMap*"],
    allowResources: ["arn:aws:geo:*:*:map/*"],
    allowReferers: ["https://example.com/*"],
  },
  expireTime: "2027-01-01T00:00:00Z",
});

BatchDeleteDevicePositionHistory

Source: src/AWS/Location/BatchDeleteDevicePositionHistory.ts

Deletes the complete position history of up to 100 devices from the tracker.

Runtime binding for the BatchDeleteDevicePositionHistory operation (IAM action geo:BatchDeleteDevicePositionHistory), scoped to one Tracker. Provide the implementation with Effect.provide(AWS.Location.BatchDeleteDevicePositionHistoryHttp).

BatchDeleteDevicePositionHistory: Updating Device Positions

const deleteHistory = yield* Location.BatchDeleteDevicePositionHistory(tracker);

yield* deleteHistory({ DeviceIds: ["vehicle-1"] });

BatchDeleteGeofence

Source: src/AWS/Location/BatchDeleteGeofence.ts

Deletes up to 10 geofences from the collection in one call.

Runtime binding for the BatchDeleteGeofence operation (IAM action geo:BatchDeleteGeofence), scoped to one GeofenceCollection. Provide the implementation with Effect.provide(AWS.Location.BatchDeleteGeofenceHttp).

BatchDeleteGeofence: Managing Geofences

const batchDelete = yield* Location.BatchDeleteGeofence(collection);

yield* batchDelete({ GeofenceIds: ["warehouse"] });

BatchEvaluateGeofences

Source: src/AWS/Location/BatchEvaluateGeofences.ts

Evaluates device positions against the collection’s geofences, emitting ENTER/EXIT events to EventBridge for linked trackers.

Runtime binding for the BatchEvaluateGeofences operation (IAM action geo:BatchEvaluateGeofences), scoped to one GeofenceCollection. Provide the implementation with Effect.provide(AWS.Location.BatchEvaluateGeofencesHttp).

BatchEvaluateGeofences: Evaluating Positions Against Geofences

const evaluate = yield* Location.BatchEvaluateGeofences(collection);

yield* evaluate({
  DevicePositionUpdates: [
    {
      DeviceId: "vehicle-1",
      Position: [-122.3493, 47.6205],
      SampleTime: new Date(),
    },
  ],
});

BatchGetDevicePosition

Source: src/AWS/Location/BatchGetDevicePosition.ts

Retrieves the latest position for up to 10 devices from the tracker in one call.

Runtime binding for the BatchGetDevicePosition operation (IAM action geo:BatchGetDevicePosition), scoped to one Tracker. Provide the implementation with Effect.provide(AWS.Location.BatchGetDevicePositionHttp).

BatchGetDevicePosition: Reading Device Positions

const batchGet = yield* Location.BatchGetDevicePosition(tracker);

const result = yield* batchGet({ DeviceIds: ["vehicle-1", "vehicle-2"] });
// result.DevicePositions → found positions, result.Errors → per-device failures

BatchPutGeofence

Source: src/AWS/Location/BatchPutGeofence.ts

Stores up to 10 geofences in the collection in one call.

Runtime binding for the BatchPutGeofence operation (IAM action geo:BatchPutGeofence), scoped to one GeofenceCollection. Provide the implementation with Effect.provide(AWS.Location.BatchPutGeofenceHttp).

BatchPutGeofence: Managing Geofences

const batchPut = yield* Location.BatchPutGeofence(collection);

const result = yield* batchPut({
  Entries: [
    {
      GeofenceId: "warehouse",
      Geometry: { Circle: { Center: [-122.3493, 47.6205], Radius: 100 } },
    },
  ],
});
// result.Successes / result.Errors → per-geofence outcomes

BatchUpdateDevicePosition

Source: src/AWS/Location/BatchUpdateDevicePosition.ts

Uploads position updates for up to 10 devices to the tracker (also triggers geofence evaluation for linked collections).

Runtime binding for the BatchUpdateDevicePosition operation (IAM action geo:BatchUpdateDevicePosition), scoped to one Tracker. Provide the implementation with Effect.provide(AWS.Location.BatchUpdateDevicePositionHttp).

BatchUpdateDevicePosition: Updating Device Positions

const updatePositions = yield* Location.BatchUpdateDevicePosition(tracker);

yield* updatePositions({
  Updates: [
    {
      DeviceId: "vehicle-1",
      Position: [-122.3493, 47.6205], // [longitude, latitude]
      SampleTime: new Date(),
    },
  ],
});

CalculateRoute

Source: src/AWS/Location/CalculateRoute.ts

Calculates a route (distance, duration, and legs) between a departure and a destination position.

Runtime binding for the CalculateRoute operation (IAM action geo:CalculateRoute), scoped to one RouteCalculator. Provide the implementation with Effect.provide(AWS.Location.CalculateRouteHttp).

CalculateRoute: Calculating Routes

const calculateRoute = yield* Location.CalculateRoute(calculator);

const route = yield* calculateRoute({
  DeparturePosition: [-122.3493, 47.6205],
  DestinationPosition: [-122.3321, 47.6062],
});
// route.Summary.Distance, route.Summary.DurationSeconds

CalculateRouteMatrix

Source: src/AWS/Location/CalculateRouteMatrix.ts

Calculates the distance/duration matrix between sets of departure and destination positions.

Runtime binding for the CalculateRouteMatrix operation (IAM action geo:CalculateRouteMatrix), scoped to one RouteCalculator. Provide the implementation with Effect.provide(AWS.Location.CalculateRouteMatrixHttp).

CalculateRouteMatrix: Calculating Routes

const calculateMatrix = yield* Location.CalculateRouteMatrix(calculator);

const matrix = yield* calculateMatrix({
  DeparturePositions: [[-122.3493, 47.6205]],
  DestinationPositions: [[-122.3321, 47.6062], [-122.2015, 47.6101]],
});
// matrix.RouteMatrix[departure][destination].Distance

CancelJob

Source: src/AWS/Location/CancelJob.ts

Cancels a running Location batch metadata job.

Runtime binding for the CancelJob operation (IAM action geo:CancelJob), account-scoped — batch jobs are created at runtime so the grant is on *. Provide the implementation with Effect.provide(AWS.Location.CancelJobHttp).

CancelJob: Managing Batch Jobs

const cancelJob = yield* Location.CancelJob();

yield* cancelJob({ JobId: jobId });

ForecastGeofenceEvents

Source: src/AWS/Location/ForecastGeofenceEvents.ts

Forecasts which geofences a device will enter or exit given its position and speed.

Runtime binding for the ForecastGeofenceEvents operation (IAM action geo:ForecastGeofenceEvents), scoped to one GeofenceCollection. Provide the implementation with Effect.provide(AWS.Location.ForecastGeofenceEventsHttp).

ForecastGeofenceEvents: Evaluating Positions Against Geofences

const forecast = yield* Location.ForecastGeofenceEvents(collection);

const events = yield* forecast({
  DeviceState: { Position: [-122.3493, 47.6205], Speed: 20 },
  TimeHorizonMinutes: 30,
});
// events.ForecastedEvents → [{ GeofenceId, EventType, NearestDistance }, …]

GeofenceCollection

Source: src/AWS/Location/GeofenceCollection.ts

An Amazon Location Service geofence collection. A geofence collection stores geofences and evaluates device positions against them. The KMS key is immutable; the description can be updated in place.

GeofenceCollection: Creating Geofence Collections

Basic Geofence Collection

import * as Location from "alchemy/AWS/Location";

const collection = yield* Location.GeofenceCollection("Fences", {});

Encrypted Geofence Collection

const collection = yield* Location.GeofenceCollection("SecureFences", {
  kmsKeyId: "alias/my-key",
  description: "Encrypted geofence collection",
});

GetDevicePosition

Source: src/AWS/Location/GetDevicePosition.ts

Retrieves a device’s most recent position reported to the tracker.

Runtime binding for the GetDevicePosition operation (IAM action geo:GetDevicePosition), scoped to one Tracker. Provide the implementation with Effect.provide(AWS.Location.GetDevicePositionHttp).

GetDevicePosition: Reading Device Positions

const getPosition = yield* Location.GetDevicePosition(tracker);

const latest = yield* getPosition({ DeviceId: "vehicle-1" });
// latest.Position → [longitude, latitude]

GetDevicePositionHistory

Source: src/AWS/Location/GetDevicePositionHistory.ts

Retrieves the position history of a device from the tracker (positions are retained for 30 days).

Runtime binding for the GetDevicePositionHistory operation (IAM action geo:GetDevicePositionHistory), scoped to one Tracker. Provide the implementation with Effect.provide(AWS.Location.GetDevicePositionHistoryHttp).

GetDevicePositionHistory: Reading Device Positions

const getHistory = yield* Location.GetDevicePositionHistory(tracker);

const history = yield* getHistory({ DeviceId: "vehicle-1" });
// history.DevicePositions → chronological position samples

GetGeofence

Source: src/AWS/Location/GetGeofence.ts

Retrieves a geofence’s geometry and status from the collection.

Runtime binding for the GetGeofence operation (IAM action geo:GetGeofence), scoped to one GeofenceCollection. Provide the implementation with Effect.provide(AWS.Location.GetGeofenceHttp).

GetGeofence: Reading Geofences

const getGeofence = yield* Location.GetGeofence(collection);

const fence = yield* getGeofence({ GeofenceId: "warehouse" });
// fence.Status → "ACTIVE" once evaluable

GetJob

Source: src/AWS/Location/GetJob.ts

Retrieves the status, configuration, and error report of a Location batch metadata job.

Runtime binding for the GetJob operation (IAM action geo:GetJob), account-scoped — batch jobs are created at runtime so the grant is on *. Provide the implementation with Effect.provide(AWS.Location.GetJobHttp).

GetJob: Managing Batch Jobs

const getJob = yield* Location.GetJob();

const job = yield* getJob({ JobId: jobId });
// job.Status → "IN_PROGRESS" | "SUCCEEDED" | …

GetMapGlyphs

Source: src/AWS/Location/GetMapGlyphs.ts

Retrieves a glyph range (font PBF) used to render map labels.

Runtime binding for the GetMapGlyphs operation (IAM action geo:GetMapGlyphs), scoped to one Map. Provide the implementation with Effect.provide(AWS.Location.GetMapGlyphsHttp).

GetMapGlyphs: Serving Map Assets

const getGlyphs = yield* Location.GetMapGlyphs(map);

const glyphs = yield* getGlyphs({
  FontStack: "Arial Regular",
  FontUnicodeRange: "0-255.pbf",
});
// glyphs.Blob → protobuf-encoded glyph bytes

GetMapSprites

Source: src/AWS/Location/GetMapSprites.ts

Retrieves the map’s sprite sheet (PNG) or sprite index (JSON) used to render icons.

Runtime binding for the GetMapSprites operation (IAM action geo:GetMapSprites), scoped to one Map. Provide the implementation with Effect.provide(AWS.Location.GetMapSpritesHttp).

GetMapSprites: Serving Map Assets

const getSprites = yield* Location.GetMapSprites(map);

const sprites = yield* getSprites({ FileName: "sprites.json" });
// sprites.Blob → sprite index JSON bytes

GetMapStyleDescriptor

Source: src/AWS/Location/GetMapStyleDescriptor.ts

Retrieves the map’s style descriptor document (the MapLibre/Mapbox GL style JSON).

Runtime binding for the GetMapStyleDescriptor operation (IAM action geo:GetMapStyleDescriptor), scoped to one Map. Provide the implementation with Effect.provide(AWS.Location.GetMapStyleDescriptorHttp).

GetMapStyleDescriptor: Serving Map Assets

const getStyle = yield* Location.GetMapStyleDescriptor(map);

const style = yield* getStyle();
// style.Blob → style JSON bytes, style.ContentType → "application/json"

GetMapTile

Source: src/AWS/Location/GetMapTile.ts

Retrieves a single map tile (vector or raster) addressed by zoom/x/y.

Runtime binding for the GetMapTile operation (IAM action geo:GetMapTile), scoped to one Map. Provide the implementation with Effect.provide(AWS.Location.GetMapTileHttp).

GetMapTile: Serving Map Assets

const getTile = yield* Location.GetMapTile(map);

const tile = yield* getTile({ Z: "0", X: "0", Y: "0" });
// tile.Blob → tile bytes, tile.ContentType → e.g. "application/vnd.mapbox-vector-tile"

GetPlace

Source: src/AWS/Location/GetPlace.ts

Fetches the full details of a place by the PlaceId returned from a search.

Runtime binding for the GetPlace operation (IAM action geo:GetPlace), scoped to one PlaceIndex. Provide the implementation with Effect.provide(AWS.Location.GetPlaceHttp).

GetPlace: Searching Places

const getPlace = yield* Location.GetPlace(index);

const place = yield* getPlace({ PlaceId: placeId });
// place.Place.Label, place.Place.Geometry.Point

ListDevicePositions

Source: src/AWS/Location/ListDevicePositions.ts

Lists the latest position of every device reported to the tracker, optionally filtered by a polygon.

Runtime binding for the ListDevicePositions operation (IAM action geo:ListDevicePositions), scoped to one Tracker. Provide the implementation with Effect.provide(AWS.Location.ListDevicePositionsHttp).

ListDevicePositions: Reading Device Positions

const listPositions = yield* Location.ListDevicePositions(tracker);

const page = yield* listPositions();
// page.Entries → [{ DeviceId, Position, SampleTime }, …]

ListGeofences

Source: src/AWS/Location/ListGeofences.ts

Lists the geofences stored in the collection.

Runtime binding for the ListGeofences operation (IAM action geo:ListGeofences), scoped to one GeofenceCollection. Provide the implementation with Effect.provide(AWS.Location.ListGeofencesHttp).

ListGeofences: Reading Geofences

const listGeofences = yield* Location.ListGeofences(collection);

const page = yield* listGeofences();
// page.Entries → [{ GeofenceId, Geometry, Status }, …]

ListJobs

Source: src/AWS/Location/ListJobs.ts

Lists the account’s Location batch metadata jobs (e.g. batch address validation jobs).

Runtime binding for the ListJobs operation (IAM action geo:ListJobs), account-scoped — batch jobs are created at runtime so the grant is on *. Provide the implementation with Effect.provide(AWS.Location.ListJobsHttp).

ListJobs: Managing Batch Jobs

const listJobs = yield* Location.ListJobs();

const page = yield* listJobs();
// page.Entries → [{ JobId, Status, Action }, …]

Map

Source: src/AWS/Location/Map.ts

An Amazon Location Service map resource. A map exposes vector/raster tiles, glyphs, and sprites for a chosen base style. The map style is immutable; the political view and description can be updated in place.

Map: Creating Maps

Basic Map

import * as Location from "alchemy/AWS/Location";

const map = yield* Location.Map("AppMap", {
  configuration: { style: "VectorEsriNavigation" },
});

Map with Political View

const map = yield* Location.Map("RegionMap", {
  configuration: { style: "VectorHereExplore", politicalView: "IND" },
  description: "Map with India political view",
});

PlaceIndex

Source: src/AWS/Location/PlaceIndex.ts

An Amazon Location Service place index. A place index geocodes text and positions against a chosen data provider. The data source is immutable; the intended use and description can be updated in place.

PlaceIndex: Creating Place Indexes

Basic Place Index

import * as Location from "alchemy/AWS/Location";

const index = yield* Location.PlaceIndex("Places", {
  dataSource: "Esri",
});

Storage-Intent Place Index

const index = yield* Location.PlaceIndex("Geocoder", {
  dataSource: "Here",
  intendedUse: "Storage",
  description: "Cacheable geocoding index",
});

PutGeofence

Source: src/AWS/Location/PutGeofence.ts

Stores (creates or replaces) a single geofence geometry in the collection.

Runtime binding for the PutGeofence operation (IAM action geo:PutGeofence), scoped to one GeofenceCollection. Provide the implementation with Effect.provide(AWS.Location.PutGeofenceHttp).

PutGeofence: Managing Geofences

const putGeofence = yield* Location.PutGeofence(collection);

yield* putGeofence({
  GeofenceId: "warehouse",
  Geometry: { Circle: { Center: [-122.3493, 47.6205], Radius: 100 } },
});

RouteCalculator

Source: src/AWS/Location/RouteCalculator.ts

An Amazon Location Service route calculator. A route calculator computes routes and route matrices against a chosen data provider. The data source is immutable; the description can be updated in place.

RouteCalculator: Creating Route Calculators

import * as Location from "alchemy/AWS/Location";

const calculator = yield* Location.RouteCalculator("Routes", {
  dataSource: "Esri",
});

SearchPlaceIndexForPosition

Source: src/AWS/Location/SearchPlaceIndexForPosition.ts

Reverse-geocodes a coordinate into the nearest addresses and places.

Runtime binding for the SearchPlaceIndexForPosition operation (IAM action geo:SearchPlaceIndexForPosition), scoped to one PlaceIndex. Provide the implementation with Effect.provide(AWS.Location.SearchPlaceIndexForPositionHttp).

SearchPlaceIndexForPosition: Searching Places

const searchPosition = yield* Location.SearchPlaceIndexForPosition(index);

const results = yield* searchPosition({
  Position: [-122.3493, 47.6205], // [longitude, latitude]
  MaxResults: 1,
});
// results.Results[0].Place.Label → nearest address

SearchPlaceIndexForSuggestions

Source: src/AWS/Location/SearchPlaceIndexForSuggestions.ts

Returns typeahead suggestions for a partial text query (autocomplete).

Runtime binding for the SearchPlaceIndexForSuggestions operation (IAM action geo:SearchPlaceIndexForSuggestions), scoped to one PlaceIndex. Provide the implementation with Effect.provide(AWS.Location.SearchPlaceIndexForSuggestionsHttp).

SearchPlaceIndexForSuggestions: Searching Places

const suggest = yield* Location.SearchPlaceIndexForSuggestions(index);

const results = yield* suggest({
  Text: "coffee",
  BiasPosition: [-122.3493, 47.6205],
  MaxResults: 5,
});
// results.Results → [{ Text, PlaceId }, …]

SearchPlaceIndexForText

Source: src/AWS/Location/SearchPlaceIndexForText.ts

Geocodes a free-form text query (address, place name, business) into ranked places with coordinates.

Runtime binding for the SearchPlaceIndexForText operation (IAM action geo:SearchPlaceIndexForText), scoped to one PlaceIndex. Provide the implementation with Effect.provide(AWS.Location.SearchPlaceIndexForTextHttp).

SearchPlaceIndexForText: Searching Places

const searchText = yield* Location.SearchPlaceIndexForText(index);

const results = yield* searchText({
  Text: "Space Needle, Seattle, WA",
  MaxResults: 3,
});
// results.Results[0].Place.Geometry.Point → [longitude, latitude]

StartJob

Source: src/AWS/Location/StartJob.ts

Starts a Location batch metadata job (e.g. batch address validation over an S3 input file).

Runtime binding for the StartJob operation (IAM action geo:StartJob). Bind the IAM Role Location assumes to read the S3 input and write the S3 output — its ARN is injected as ExecutionRoleArn and the host is additionally granted iam:PassRole on it. Jobs are named at runtime so the geo:StartJob grant is on *. Provide the implementation with Effect.provide(AWS.Location.StartJobHttp).

StartJob: Managing Batch Jobs

const startJob = yield* Location.StartJob(jobsRole);

const job = yield* startJob({
  Action: "ValidateAddress",
  InputOptions: { Format: "CSV", Location: "s3://my-bucket/addresses.csv" },
  OutputOptions: { Format: "CSV", Location: "s3://my-bucket/results/" },
});
// job.JobId → poll with Location.GetJob

Tracker

Source: src/AWS/Location/Tracker.ts

An Amazon Location Service tracker. A tracker records device positions and evaluates them against linked geofence collections. The KMS key is immutable; position filtering, EventBridge publishing, and the description can be updated in place.

Tracker: Creating Trackers

Basic Tracker

import * as Location from "alchemy/AWS/Location";

const tracker = yield* Location.Tracker("Devices", {});

Distance-Filtered Tracker with EventBridge

const tracker = yield* Location.Tracker("Fleet", {
  positionFiltering: "DistanceBased",
  eventBridgeEnabled: true,
});

TrackerConsumer

Source: src/AWS/Location/TrackerConsumer.ts

Links an Amazon Location Tracker to a GeofenceCollection so every device position uploaded to the tracker is automatically evaluated against the collection’s geofences, emitting ENTER/EXIT events (delivered to EventBridge — see consumeTrackerEvents).

The association is existence-only: both properties are immutable and any change replaces it.

TrackerConsumer: Linking Trackers to Geofence Collections

import * as Location from "alchemy/AWS/Location";

const tracker = yield* Location.Tracker("Fleet", {
  eventBridgeEnabled: true,
});
const fences = yield* Location.GeofenceCollection("Zones", {});

const link = yield* Location.TrackerConsumer("FleetZones", {
  trackerName: tracker.trackerName,
  consumerArn: fences.collectionArn,
});

VerifyDevicePosition

Source: src/AWS/Location/VerifyDevicePosition.ts

Verifies a reported device position against cellular, Wi-Fi, and IP signals to detect spoofed GPS locations.

Runtime binding for the VerifyDevicePosition operation (IAM action geo:VerifyDevicePosition), scoped to one Tracker. Provide the implementation with Effect.provide(AWS.Location.VerifyDevicePositionHttp).

VerifyDevicePosition: Verifying Device Positions

const verifyPosition = yield* Location.VerifyDevicePosition(tracker);

const verdict = yield* verifyPosition({
  DeviceState: {
    DeviceId: "vehicle-1",
    SampleTime: new Date(),
    Position: [-122.3493, 47.6205],
    WiFiAccessPoints: [{ MacAddress: "A0:EC:F9:1E:32:C1", Rss: -66 }],
  },
});
// verdict.InferredState → inferred position + accuracy