Amazon Location Service

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

Jobs (SDK: location, JS: @aws-sdk/client-location)

• Address Validation: Verify and standardize addresses in bulk with the asynchronous Jobs API (StartJob with Action ValidateAddress, then GetJob/ListJobs/CancelJob). It adds what Geocode lacks — a postal-authority verdict (ValidationGranularity, Mailable/Locatable, per-component StatusDetail), not just coordinates. Coverage is US, CA, UK, and AU only; for other countries use Geocode.

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

• Dynamic Maps: Interactive maps using tiles with MapLibre 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 (client-side) or SigV4/IAM (server-side) for Geofencing/Tracking; SigV4/IAM role for the Jobs API / Address Validation (StartJob/GetJob/ListJobs/CancelJob). API keys authenticate ONLY Maps/Places/Routes — they do NOT work for Geofencing, Tracking, or Jobs operations.
• 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 (interactive forms)

• Autocomplete → Type-ahead in address forms (partial input: "123 Main")
• GetPlace → Get full details after user selects autocomplete result (by PlaceId)
• Geocode → Resolve a complete user-typed address to coordinates. Returns coordinates, a matched label, and match quality (MatchScores overall + per-component, AddressNumberCorrected) synchronously in one call — but no postal-deliverability verdict or standardized output.

Address Validation (verify & standardize)

• StartJob (Action ValidateAddress) → Verify and standardize addresses in bulk against authoritative postal data; async Jobs API with Parquet input/output in Amazon S3. Coverage: US, CA, UK, AU only; for other countries use Geocode.
• GetJob / ListJobs / CancelJob → Track, enumerate, and cancel validation jobs
• Choose the Jobs API when you need a postal-authority verdict (ValidationGranularity, Mailable/Locatable, per-component StatusDetail) or bulk throughput. For a single ad-hoc check of whether one address resolves and how well it matched, the synchronous Geocode MatchScores is the right tool — do not stand up a job. See the address-verification reference.

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

• Dynamic Maps (tiles + MapLibre) → Interactive maps requiring pan, zoom, markers
• Static Maps (image) → Non-interactive map images for thumbnails or email

Routing

• CalculateRoutes → Single route between origin and destination
• CalculateRouteMatrix → Multiple origins/destinations travel times
• CalculateIsolines → Service areas (all locations reachable within time/distance)

LLM Context Files

When you need detailed API parameter specifications or service capabilities not covered in the reference files, fetch these llms.txt resources:

• Developer Guide: https://docs.aws.amazon.com/location/latest/developerguide/llms.txt
• API Reference: https://docs.aws.amazon.com/location/latest/APIReference/llms.txt

Key Guidance for Better Recommendations

Prefer the Bundled JavaScript Client for Web Development

For convenient web application development, Amazon Location Service provides a bundled JavaScript client that simplifies integration and provides optimized functionality without custom bundling. This bundled client includes all libraries required to build client side web applications with Amazon Location Service.

Features included in the bundled client:

• Enables direct pre-bundled dependency inclusion without custom bundle / build
• Simplified authentication and API integration
• TypeScript support with comprehensive type definitions
• Support for all Amazon Location SDKs

Included SDKs and Libraries:

• @aws-sdk/client-geo-maps
• @aws-sdk/client-geo-places
• @aws-sdk/client-geo-routes
• @aws-sdk/client-location
• @aws-sdk/credential-providers
• https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js

Resources:

• NPM Package: @aws/amazon-location-client
• GitHub Repository: aws-geospatial/amazon-location-client-js

Prefer Resourceless Operations

Amazon Location Places, Maps and Routes services offer both resource-based and resourceless API operations. Resourceless operations are often simpler and more appropriate for many use cases.

Resource-based operations require you to:

• Create and configure Amazon Location Service resources (maps, place indexes, route calculators)
• Manage resource lifecycle and permissions
• Handle resource naming and organization

Resourceless operations allow you to:

• Make API calls directly without pre-creating resources
• Reduce deployment complexity
• Simplify IAM permissions and API Key permissions

Authentication and Permissions

When discussing permissions for Amazon Location Places, Maps and Routes services, always include both IAM permissions and API Key permissions in your guidance. If the type of application being developed is clear, recommend the appropriate authorization tool as described below:

IAM Permissions - Recommended for server-side applications and AWS SDK usage:

• Used with AWS credentials (access keys, roles, etc.)
• Provide fine-grained access control
• Required for resource management operations

API Key Permissions - Alternative authentication method, especially useful for client-side applications or applications deployed to unauthenticated (public) users:

• Simplified authentication without exposing AWS credentials
• Can be configured with specific allowed operations
• Useful for web and mobile applications
• Supports both resource-based and resourceless operations
• Enables faster subsequent map loads through CDN caching

Jobs API / Address Validation, Geofencing, and Tracking - These operations are NOT API-key-eligible. API keys authenticate only Maps, Places, and Routes.

• Jobs API / Address Validation (StartJob with Action ValidateAddress, GetJob, ListJobs, CancelJob): server-side/back-office operations that MUST be called with SigV4 request signing backed by an IAM role or IAM user credentials — never an API key. StartJob also takes an ExecutionRoleArn (a separate IAM role that Amazon Location assumes to read/write your S3 buckets); that is in addition to the calling identity SigV4/IAM credentials, not a substitute for them. See the address-verification reference.
• Geofencing and Tracking: SigV4/IAM for server-side callers, or an Amazon Cognito identity pool for client-side (browser/mobile) callers. Not API-key-eligible.

API Key Action Names - API keys use their own action naming convention. Do NOT use SDK client names or IAM action names — they will be rejected.

Resourceless API key actions (recommended):

Do NOT use legacy geo: prefixed actions (e.g., geo:GetMap*, geo:CalculateRoute) — these are for pre-created resources only and will not work with resourceless APIs.

LocationClient Setup

Geofencing and Tracking use LocationClient (@aws-sdk/client-location). These are resource-based operations — you MUST create resources (trackers, geofence collections) before using them.

import { LocationClient } from "@aws-sdk/client-location";

// Server-side: uses IAM credentials from environment/role
const client = new LocationClient({ region: "us-east-1" });

// Client-side: uses Amazon Cognito
import { LocationClient } from "@aws-sdk/client-location";
import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers";

const client = new LocationClient({
  region: "us-east-1",
  credentials: fromCognitoIdentityPool({
    identityPoolId: "us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    clientConfig: { region: "us-east-1" },
  }),
});

MCP Server Integration

Integrates with the AWS MCP Server (Apache-2.0 license) which provides access to AWS documentation, API references, and direct API interactions. See the Getting Started Guide for setup and credential configuration. To use a non-default region, add "--metadata", "AWS_REGION=<your-region>" to your MCP config args.

Additional Resources

• Amazon Location Service Developer Guide
• Amazon Location Service API Reference
• Amazon Location Service Samples

Reference Files

Load these resources as needed for specific implementation guidance:

• Address Input - Create effective address input forms for users with address type ahead completion improving input speed and accuracy
• Address Verification - Verify and standardize addresses in bulk against authoritative postal data using the asynchronous Jobs API (StartJob with Action ValidateAddress), before persisting to databases or taking downstream actions
• Calculate Routes - Calculate routes between locations with customizable travel options and display them on maps
• Device Tracking - Track device locations in real time and query position history
• Dynamic Map Rendering - Render dynamic maps with MapLibre
• Google Maps Migration (Android) - Migrate Android application from Google Maps SDK for Android to Amazon Location Service
• Google Maps Migration (iOS) - Migrate iOS application from Google Maps SDK for iOS to Amazon Location Service
• Google Maps Migration (JavaScript) - Migrate JavaScript web application from Google Maps API to Amazon Location Service
• Places Search - Search for places or points of interest
• Web JavaScript - Integrate Amazon Location services into web browser applications
• Zone Alerts - Monitor device positions against geographic boundaries and react to zone entry or exit