AutoGineer
Generated banner for Amazon Location Service
Generated logo for Amazon Location Service

Amazon Location Service

ClineOfficialCreated by aws-geospatialDistributed by Cline

  • Skill
  • Tool integration
  • Cloud and DevOps
  • MIT-0
  • No issues found
Download ZIP

From the author

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.
— the description by aws-geospatial

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Amazon Location Service provides a suite of geospatial APIs for web and mobile applications. This skill covers the integration of maps, geocoding, routing, places search, geofencing, and device tracking. It emphasizes using the bundled JavaScript client for web development and leveraging resourceless API operations to simplify deployment and IAM management. The skill provides guidance on authentication via API keys or Cognito, proper MapLibre configuration, and best practices for address input and verification.

What it does

  • Provides interactive maps using MapLibre or static map images.
  • Converts addresses to coordinates (geocoding) and coordinates to addresses (reverse geocoding).
  • Calculates routes, travel times, and service areas with traffic estimation.
  • Enables text-based place search, nearby search, and autocomplete suggestions.
  • Monitors geographical boundaries with geofences and tracks device locations.
  • Simplifies authentication using API keys for public apps or Cognito for secure resources.

When to use it

  • When building location-aware web or mobile applications on AWS.
  • When you need to implement address autocomplete, validation, or standardization.
  • When integrating interactive maps or route calculation into your software.
  • When you need to track assets or monitor geofence entry and exit events.
  • When migrating existing geospatial features to Amazon Location Service.

Advantages

  • Reduces complexity by supporting resourceless API operations.
  • Simplifies web integration with a pre-bundled JavaScript client.
  • Provides granular control over authentication via IAM or API keys.
  • Ensures consistent data quality through standardized address verification.
  • Optimizes performance by using direct URL passing for map styles.

Usage examples

“How do I implement an address autocomplete field for my web form?”
The agent will guide you to use the Autocomplete API, display Address.Label instead of Title, and use GetPlace to retrieve full details once a user selects a suggestion.
“How should I authenticate my map component for a public website?”
The agent will recommend using an API Key with restricted AllowActions (e.g., geo-maps:GetTile) to avoid exposing AWS credentials while enabling map rendering.
“What is the best way to verify a user-submitted address before saving it to my database?”
The agent will advise using the Geocode API to validate and standardize the address string, checking for multiple matches to handle ambiguity.
“How do I initialize a MapLibre map with Amazon Location Service?”
The agent will provide the configuration steps, including passing the style descriptor URL directly and setting validateStyle to false for faster loading.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/cline/amazon-location-service/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip amazon-location-service.zip -d .agents/skills

Documentation by aws-geospatial

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

  • 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:

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:

Resources:

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

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

ServiceAllowActionsAllowResources
Mapsgeo-maps:GetTile, geo-maps:GetStaticMaparn:aws:geo-maps:REGION::provider/default
Placesgeo-places:Autocomplete, geo-places:Geocode, geo-places:ReverseGeocode, geo-places:SearchText, geo-places:SearchNearby, geo-places:Suggest, geo-places:GetPlacearn:aws:geo-places:REGION::provider/default
Routesgeo-routes:CalculateRoutes, geo-routes:CalculateRouteMatrix, geo-routes:CalculateIsolines, geo-routes:OptimizeWaypoints, geo-routes:SnapToRoadsarn:aws:geo-routes:REGION::provider/default

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.

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

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 - Validate addresses input from users before taking actions or persisting to databases

  • Calculate Routes - Calculate routes between locations with customizable travel options and display them on maps

  • Dynamic Map Rendering - Render dynamic maps with MapLibre

  • Places Search - Search for places or points of interest

  • Web JavaScript - Integrate Amazon Location services into web browser applications

Files

references/dynamic-map.md

Dynamic Map Rendering

Audience Note: Keywords MUST, SHOULD, MAY in this document indicate requirements for agent recommendations to users, following RFC 2119.

Render interactive maps using MapLibre GL JS with Amazon Location Service.

Table of Contents

  • Basic Setup

  • Complete Examples

  • Map Styles

  • Advanced Features

  • Error Handling

  • Best Practices

Basic Setup

HTML Structure
<!DOCTYPE html>
<html>
  <head>
    <link
      href="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css"
      rel="stylesheet"
    />
    <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5"></script>
    <style>
      #map {
        height: 500px;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script src="app.js"></script>
  </body>
</html>
Minimal Map Initialization
const API_KEY = "your-api-key";
const REGION = "us-west-2";

// Direct URL method - REQUIRED
const styleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}`;

const map = new maplibregl.Map({
  container: "map",
  style: styleUrl,
  center: [-97.7723, 30.2672], // [longitude, latitude] - Zilker Park, Austin
  zoom: 10,
  validateStyle: false, // MUST set to false for faster loading
});
validateStyle Parameter

Always set validateStyle: false

  • With false: Map loads faster, skips unnecessary validation of Amazon's trusted styles

  • With true (default): MapLibre validates every style property, adding ~500ms+ load time

  • Trade-off: Validation helps catch errors in custom styles, but Amazon styles are pre-validated

Complete Examples

Map with Markers and Popups
const API_KEY = "your-api-key";
const REGION = "us-west-2";

const styleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}`;

const map = new maplibregl.Map({
  container: "map",
  style: styleUrl,
  center: [-97.7723, 30.2672], // Zilker Park, Austin TX
  zoom: 12,
  validateStyle: false,
});

// Wait for map to load before adding markers
map.on("load", () => {
  console.log("Map loaded successfully");

  // Add marker with popup
  const marker = new maplibregl.Marker({ color: "#FF0000" })
    .setLngLat([-97.7723, 30.2672])
    .setPopup(
      new maplibregl.Popup({ offset: 25 }).setHTML(
        "<h3>Zilker Park</h3><p>Austin, Texas</p>",
      ),
    )
    .addTo(map);

  // Add multiple markers from data
  const locations = [
    { name: "Barton Springs Pool", coords: [-97.7708, 30.2639] },
    { name: "Zilker Botanical Garden", coords: [-97.7716, 30.2707] },
  ];

  locations.forEach((loc) => {
    new maplibregl.Marker()
      .setLngLat(loc.coords)
      .setPopup(new maplibregl.Popup().setHTML(`<h4>${loc.name}</h4>`))
      .addTo(map);
  });
});

// Handle errors
map.on("error", (e) => {
  console.error("Map error:", e);
  // Show user-friendly error message
});

Map Styles

Available Styles

Amazon Location provides four map styles:

  • Standard (default) - General purpose map

  • Monochrome - Simplified single-color palette

  • Hybrid - Satellite imagery with labels

  • Satellite - Satellite imagery only

// Standard style (default)
const styleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}`;

// Other styles
const monochromeUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Monochrome/descriptor?key=${API_KEY}`;
const hybridUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Hybrid/descriptor?key=${API_KEY}`;
const satelliteUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Satellite/descriptor?key=${API_KEY}`;
Common Customizations

Dark mode:

const styleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}&color-scheme=Dark`;

3D buildings:

const styleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}&buildings=Buildings3D`;

Traffic overlay:

const styleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}&traffic=All`;

Combined customizations:

const styleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}&color-scheme=Dark&buildings=Buildings3D&traffic=All`;

For all customization options (terrain, political views, travel modes, etc.), see the GetStyleDescriptor API Reference.

Feature Compatibility by Map Style

Not all features are available on every map style. Applying an unsupported feature parameter to an incompatible style will have no effect.

FeatureStandardMonochromeHybridSatellite
Color Scheme (Light/Dark)YesYesNoNo
Terrain (Hillshade)YesYesNoNo
Terrain (Terrain3D)YesYesYesYes
Contour DensityYesYesYesNo
TrafficYesNoNoNo
Buildings (3D)YesYesNoNo
Travel Modes (Transit/Truck)YesNoNoNo
LanguageYesYesYesNo
Political ViewYesYesYesNo

Note: Traffic and Travel Modes are only supported on the Standard map style. If you need real-time traffic visualization or transit/truck overlays, you must use Standard. See Map concepts for the full compatibility matrix.

Style Change Persistence

Calling map.setStyle() completely replaces the map's style object. This destroys all custom sources and layers added via map.addSource() / map.addLayer() — route lines, geofence polygons, heatmaps, cluster layers, etc. DOM-based elements like maplibregl.Marker survive because they exist outside the style.

Any code that switches map styles MUST re-add custom layers after the new style loads. The recommended pattern is:

  1. Store the data needed to recreate custom layers (coordinates, paint options, etc.)

  2. Listen for style.load after calling setStyle() and re-add the layers

  3. Clear stored data only when layers are intentionally removed

// Track data for any custom layers that need to survive style changes
let customLayerData = null;

function addCustomLayer(sourceId, layerId, geojsonData, paintOptions) {
  customLayerData = { sourceId, layerId, geojsonData, paintOptions };

  map.addSource(sourceId, { type: "geojson", data: geojsonData });
  map.addLayer({
    id: layerId,
    type: "line",
    source: sourceId,
    paint: paintOptions,
  });
}

function removeCustomLayer() {
  if (map.getLayer(customLayerData?.layerId))
    map.removeLayer(customLayerData.layerId);
  if (map.getSource(customLayerData?.sourceId))
    map.removeSource(customLayerData.sourceId);
  customLayerData = null;
}

function setMapStyle(styleName) {
  const url = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/${styleName}/descriptor?key=${API_KEY}`;
  map.setStyle(url);

  map.once("style.load", () => {
    if (customLayerData) {
      addCustomLayer(
        customLayerData.sourceId,
        customLayerData.layerId,
        customLayerData.geojsonData,
        customLayerData.paintOptions,
      );
    }
  });
}

Advanced Features

Navigation Controls
map.on("load", () => {
  // Add zoom and rotation controls
  map.addControl(new maplibregl.NavigationControl(), "top-right");

  // Add geolocation control
  map.addControl(
    new maplibregl.GeolocateControl({
      positionOptions: { enableHighAccuracy: true },
      trackUserLocation: true,
    }),
    "top-right",
  );

  // Add scale control
  map.addControl(new maplibregl.ScaleControl(), "bottom-left");
});
Custom Markers with HTML
// Create custom marker element
const el = document.createElement("div");
el.className = "custom-marker";
el.style.width = "30px";
el.style.height = "30px";
el.style.backgroundImage = "url(marker-icon.png)";

new maplibregl.Marker({ element: el })
  .setLngLat([-122.4194, 37.7749])
  .addTo(map);
Map Event Handling
// Click event
map.on("click", (e) => {
  console.log("Clicked at:", e.lngLat);
  new maplibregl.Marker().setLngLat(e.lngLat).addTo(map);
});

// Move event
map.on("move", () => {
  console.log("Center:", map.getCenter());
  console.log("Zoom:", map.getZoom());
});

Error Handling

Common Errors
map.on("error", (e) => {
  console.error("Map error:", e.error);

  if (e.error.status === 401) {
    // Invalid API key
    showError("Authentication failed. Check your API key.");
  } else if (e.error.status === 403) {
    // API key lacks permissions
    showError("API key does not have permission to access maps.");
  } else if (e.error.message.includes("Failed to fetch")) {
    // Network error
    showError("Network error. Please check your connection.");
  } else {
    showError("Failed to load map. Please try again.");
  }
});

function showError(message) {
  document.getElementById("map").innerHTML =
    `<div style="padding: 20px; color: red;">${message}</div>`;
}

Best Practices

Performance

  • Set validateStyle: false: Saves 500ms+ on initial load

  • Lazy load MapLibre: Only load map library when user navigates to map view

  • Limit markers: Use clustering for 100+ markers (maplibre-gl-cluster)

Security

  • Restrict API key: Use API key permissions to limit to specific operations

  • Domain restrictions: Configure API key to only work from your domains

  • Never expose in public repos: Use environment variables for API keys

User Experience

  • Show loading state: Display spinner while map initializes

  • Handle errors gracefully: Show user-friendly error messages, not console errors

  • Responsive sizing: Ensure map container has explicit height

  • Touch support: MapLibre automatically handles touch events on mobile

Debugging

  • Check browser console: Map errors appear in console

  • Verify API key: Test with simple example first

  • Check network tab: Verify style descriptor and tile requests succeed

  • Test validateStyle: true: During development only, to catch custom style issues

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs an API key

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
aws-geospatial
Publisher
Cline (Official)
Distributed by
Cline
Source
cline/skills · skills/amazon-location-service · commit 2637846
Licence
MIT No Attribution (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by aws-geospatial or Cline.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download amazon-location-service.zip