/amazon-location-service

name: amazon-location-service
description: Integrates Amazon Location Service APIs for AWS applications. Use this skill when users want to add maps (interactive MapLibre or static images); geocode addresses to coordinates or reverse geocode coordinates to addresses; calculate routes, travel times, or service areas; find places and businesses through text search, nearby search, or autocomplete suggestions; retrieve detailed place information including hours, contacts, and addresses; monitor geographical boundaries with geofences; or track device locations. Covers authentication, SDK integration, and all Amazon Location Service capabilities.
license: MIT-0
metadata:
  author: aws-geospatial
  version: "1.0"

Overview

Amazon Location Service provides geospatial APIs for maps, geocoding, routing, places search, geofencing, and tracking. Prefer the bundled JavaScript client (@aws/amazon-location-client) for web development and use resourceless API operations to avoid managing AWS resources.

When to Use This Skill

Use this skill when:

• Building location-aware web or mobile applications
• Working with Amazon Location Service projects
• Implementing maps, geocoding, routing, or places search
• Adding geofencing or device tracking functionality
• Integrating geospatial features into AWS applications

Do NOT use this skill for:

• Google Maps, Mapbox, or Leaflet-with-OSM projects (unless migrating to Amazon Location)
• Generic GIS operations without AWS context
• Non-AWS geospatial services

Amazon Location Service API Overview

**Places** (SDK: geo-places, JS: @aws-sdk/client-geo-places)

• Geocode (Forward/Reverse): Convert addresses to coordinates and vice versa
• Search (Text/Nearby): Find points of interest with contact and hours info
• Autocomplete: Predict addresses based on user input
• Suggest: Predict places and points of interest based on partial or misspelled user input
• Get Place: Retrieve place details by place ID

**Maps** (SDK: geo-maps, JS: @aws-sdk/client-geo-maps)

• Dynamic Maps: Interactive maps using tiles with [MapLibre](https://maplibre.org/) rendering
• Static Maps: Pre-rendered, non-interactive map images, good for including an image into a web page, or for thumbnail images

**Routes** (SDK: geo-routes, JS: @aws-sdk/client-geo-routes)

• Route calculation with traffic and distance estimation
• Service area/isoline creation
• Matrix calculations for multiple origins/destinations
• GPS trace alignment to road segments
• Route optimization (traveling salesman problem)

**Geofences & Trackers** (SDK: location, JS: @aws-sdk/client-location)

• Geofences: Detect entry/exit from geographical boundaries
• Trackers: Current and historical device location tracking

**API Keys** (SDK: location, JS: @aws-sdk/client-location)

• API Keys: Grant access to public applications without exposing AWS credentials

Common Mistakes

Avoid these frequent errors:

1. **Using `Title` instead of `Address.Label` for display**: In Autocomplete results, always display `Address.Label`. The `Title` field may show components in reverse order and is not suitable for user-facing text.

2. **Using GetStyleDescriptor API for map initialization**: MUST use direct URL passing to MapLibre (`https://maps.geo.{region}.amazonaws.com/v2/styles/Standard/descriptor?key={apiKey}`) instead of making GetStyleDescriptor API calls. The direct URL method is required for proper map rendering.

3. **Forgetting `validateStyle: false` in MapLibre config**: Always set `validateStyle: false` in the MapLibre Map constructor for faster map load times with Amazon Location styles.

4. **Mixing resource-based and resourceless operations**: When possible, prefer resourceless operations (direct API calls without pre-created resources) for simpler deployment and permissions.

5. **Inconsistent API operation naming**: Use the format `service:Operation` when referencing APIs (e.g., `geo-places:Geocode`, `geo-maps:GetStyleDescriptor`). SDK clients use `@aws-sdk/client-*` format.

6. **Not handling nested Address objects correctly**: The Address object from GetPlace contains nested objects (`Region.Code`, `Region.Name`, `Country.Code2`, etc.), not flat strings. Access nested properties correctly.

7. **Wrong action names in API Key permissions**: API key `AllowActions` use `geo-maps:`, `geo-places:`, `geo-routes:` prefixes (e.g., `geo-places:Geocode`, `geo-routes:CalculateRoutes`). Do NOT use SDK client names (`@aws-sdk/client-geo-places`) or IAM-style actions. See the Authentication and Permissions section for the complete list.

Defaults

Use these default choices unless the user explicitly requests otherwise:

• **JavaScript SDK**: Bundled client (CDN) for browser-only apps; npm modular SDKs (@aws-sdk/client-geo-\*) for React and build tool apps
• **API operations**: Resourceless for Maps/Places/Routes (Geofencing/Tracking always require pre-created resources)
• **Authentication**: API Key for Maps/Places/Routes; Cognito for Geofencing/Tracking
• **Map style**: Standard
• **Coordinate format**: [longitude, latitude] (GeoJSON order)

Override: User can specify "use Cognito for Maps/Places/Routes" or "use bundled client for React".

API Selection Guidance

Choose the right API for your use case:

Address Input & Validation

• **Autocomplete** → Type-ahead in address forms (partial input: "123 Main")
• **GetPlace** → Get full details after user selects autocomplete result (by PlaceId)
• **Geocode** → Validate complete user-typed address or convert address to coordinates

Finding Locations

• **SearchText** → General text search ("pizza near Seattle")
• **SearchNearby** → Find places near a coordinate (restaurants within 5km)
• **Suggest** → Predict places/POIs from partial or misspelled input
• **Autocomplete** → Address-specific predictions (not for general POI search)

Geocoding

• **Geocode (Forward)** → Address string → Coordinates
• **ReverseGeocode** → Coordinates → Address

Maps

• **D