Back to Details

amazon-location-service

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
Amazon Location Service 为地图、地理编码、路线规划、地点搜索、地理围栏和位置跟踪提供地理空间API。Web开发优先使用捆绑式JavaScript客户端（@aws/amazon-location-client），并使用无资源API操作来避免管理AWS资源。

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
在以下场景使用此技能：
  • 构建位置感知型Web或移动应用
  • 开发Amazon Location Service相关项目
  • 实现地图、地理编码、路线规划或地点搜索功能
  • 添加地理围栏或设备位置跟踪功能
  • 在AWS应用中集成地理空间特性
请勿在以下场景使用此技能：
  • Google Maps、Mapbox或Leaflet-with-OSM项目（除非迁移至Amazon Location）
  • 无AWS上下文的通用GIS操作
  • 非AWS的地理空间服务

Amazon Location Service API Overview

Amazon Location Service API概述

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
地点服务（SDK: geo-places, JS: @aws-sdk/client-geo-places）
  • 地理编码（正向/反向）：将地址转换为坐标，或将坐标转换为地址
  • 搜索（文本/附近）：查找包含联系方式和营业时间信息的兴趣点
  • 自动补全：根据用户输入预测地址
  • 建议：根据部分输入或拼写错误的内容预测地点和兴趣点
  • 获取地点详情：通过地点ID检索地点详细信息
地图服务（SDK: geo-maps, JS: @aws-sdk/client-geo-maps）
  • 动态地图：使用瓦片和MapLibre渲染的交互式地图
  • 静态地图：预渲染的非交互式地图图片，适合嵌入网页或用作缩略图
路线服务（SDK: geo-routes, JS: @aws-sdk/client-geo-routes）
  • 包含交通和距离估算的路线计算
  • 服务区/等值线创建
  • 多起点/终点的矩阵计算
  • GPS轨迹与道路段对齐
  • 路线优化（旅行商问题）
地理围栏与跟踪器（SDK: location, JS: @aws-sdk/client-location）
  • 地理围栏：检测进出地理边界的行为
  • 跟踪器：设备当前位置和历史位置跟踪
API密钥（SDK: location, JS: @aws-sdk/client-location）
  • API密钥：在不暴露AWS凭证的情况下为公开应用授予访问权限

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.
避免以下常见错误：
  1. 使用
    Title
    而非
    Address.Label
    进行显示    ：在自动补全结果中，始终显示
    Address.Label
    。
    Title
    字段可能以逆序显示组件，不适合面向用户的文本。
  2. 使用GetStyleDescriptor API初始化地图：必须使用直接URL传递给MapLibre（
    https://maps.geo.{region}.amazonaws.com/v2/styles/Standard/descriptor?key={apiKey}
    ），而不是调用GetStyleDescriptor API。直接URL方法是正确渲染地图的必要条件。
  3. 在MapLibre配置中忘记设置
    validateStyle: false
    ：在MapLibre地图构造函数中始终设置
    validateStyle: false
    ，以加快Amazon Location样式的地图加载速度。
  4. 混合使用基于资源和无资源的操作：尽可能优先选择无资源操作（无需预先创建资源的直接API调用），以简化部署和权限管理。
  5. API操作命名不一致：引用API时使用
    service:Operation
    格式（例如
    geo-places:Geocode
    、
    geo-maps:GetStyleDescriptor
    ）。SDK客户端使用
    @aws-sdk/client-*
    格式。
  6. 未正确处理嵌套的Address对象：GetPlace返回的Address对象包含嵌套对象（
    Region.Code
    、
    Region.Name
    、
    Country.Code2
    等），而非扁平字符串。请正确访问嵌套属性。
  7. API密钥权限中使用错误的操作名称：API密钥的
    AllowActions
    使用
    geo-maps:
    、
    geo-places:
    、
    geo-routes:
    前缀（例如
    geo-places:Geocode
    、
    geo-routes:CalculateRoutes
    ）。请勿使用SDK客户端名称（
    @aws-sdk/client-geo-places
    ）或IAM风格的操作。完整列表请参阅身份验证与权限部分。

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".
除非用户明确要求，否则使用以下默认选项：
  • JavaScript SDK：纯浏览器应用使用捆绑式客户端（CDN）；React和构建工具应用使用npm模块化SDK（@aws-sdk/client-geo-*）
  • API操作：地图/地点/路线服务使用无资源操作（地理围栏/跟踪始终需要预先创建资源）
  • 身份验证：地图/地点/路线服务使用API密钥；地理围栏/跟踪使用Cognito
  • 地图样式：Standard
  • 坐标格式：[经度, 纬度]（GeoJSON顺序）
覆盖规则：用户可以指定“为地图/地点/路线服务使用Cognito”或“为React使用捆绑式客户端”。

API Selection Guidance

API选择指南

Choose the right API for your use case:
根据您的用例选择合适的API：

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
  • Autocomplete → 地址表单中的输入提示（部分输入："123 Main"）
  • GetPlace → 用户选择自动补全结果后获取完整详情（通过PlaceId）
  • Geocode → 验证用户输入的完整地址或将地址转换为坐标

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)
  • SearchText → 通用文本搜索（"西雅图附近的披萨店"）
  • SearchNearby → 查找坐标附近的地点（5公里范围内的餐厅）
  • Suggest → 根据部分输入或拼写错误的内容预测地点/兴趣点
  • Autocomplete → 地址专用预测（不适用于通用兴趣点搜索）

Geocoding

地理编码

  • Geocode (Forward) → Address string → Coordinates
  • ReverseGeocode → Coordinates → Address
  • Geocode（正向） → 地址字符串 → 坐标
  • ReverseGeocode → 坐标 → 地址

Maps

地图

  • Dynamic Maps (tiles + MapLibre) → Interactive maps requiring pan, zoom, markers
  • Static Maps (image) → Non-interactive map images for thumbnails or email
  • 动态地图（瓦片+MapLibre） → 需要平移、缩放、标记的交互式地图
  • 静态地图（图片） → 用于缩略图或邮件的非交互式地图图片

Routing

路线规划

  • CalculateRoutes → Single route between origin and destination
  • CalculateRouteMatrix → Multiple origins/destinations travel times
  • CalculateIsolines → Service areas (all locations reachable within time/distance)
  • CalculateRoutes → 起点和终点之间的单一路线
  • CalculateRouteMatrix → 多起点/终点的行程时间
  • CalculateIsolines → 服务区（在指定时间/距离内可达的所有地点）

LLM Context Files

LLM上下文文件

When you need detailed API parameter specifications or service capabilities not covered in the reference files, fetch these llms.txt resources:
当您需要参考文件未涵盖的详细API参数规范或服务功能时，获取以下llms.txt资源：

Key Guidance for Better Recommendations

优化建议的关键指南

Prefer the Bundled JavaScript Client for Web Development

Web开发优先使用捆绑式JavaScript客户端

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:
为方便Web应用开发，Amazon Location Service提供了捆绑式JavaScript客户端，可简化集成并提供优化功能，无需自定义打包。此捆绑式客户端包含使用Amazon Location Service构建客户端Web应用所需的所有库。
捆绑式客户端包含的功能：
  • 无需自定义打包即可直接引入预捆绑依赖
  • 简化的身份验证和API集成
  • 带有全面类型定义的TypeScript支持
  • 支持所有Amazon Location SDK
包含的SDK和库：
资源：

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
Amazon Location的地点、地图和路线服务同时提供基于资源和无资源的API操作。无资源操作通常更简单，更适合许多用例。
基于资源的操作要求您：
  • 创建并配置Amazon Location Service资源（地图、地点索引、路线计算器）
  • 管理资源生命周期和权限
  • 处理资源命名和组织
无资源操作允许您：
  • 无需预先创建资源即可直接调用API
  • 降低部署复杂度
  • 简化IAM权限和API密钥权限

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
Maps
geo-maps:GetTile
, 
geo-maps:GetStaticMap
arn:aws:geo-maps:REGION::provider/default
Places
geo-places:Autocomplete
, 
geo-places:Geocode
, 
geo-places:ReverseGeocode
, 
geo-places:SearchText
, 
geo-places:SearchNearby
, 
geo-places:Suggest
, 
geo-places:GetPlace
arn:aws:geo-places:REGION::provider/default
Routes
geo-routes:CalculateRoutes
, 
geo-routes:CalculateRouteMatrix
, 
geo-routes:CalculateIsolines
, 
geo-routes:OptimizeWaypoints
, 
geo-routes:SnapToRoads
arn: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.
讨论Amazon Location地点、地图和路线服务的权限时，指南中需同时包含IAM权限和API密钥权限。如果明确应用类型，建议使用以下相应的授权工具：
IAM权限 - 推荐用于服务器端应用和AWS SDK使用：
  • 与AWS凭证（访问密钥、角色等）配合使用
  • 提供细粒度访问控制
  • 资源管理操作必需
API密钥权限 - 替代身份验证方法，尤其适用于客户端应用或部署给未认证（公开）用户的应用：
  • 无需暴露AWS凭证的简化身份验证
  • 可配置为允许特定操作
  • 适用于Web和移动应用
  • 支持基于资源和无资源的操作
  • 通过CDN缓存加快后续地图加载速度
API密钥操作名称 - API密钥使用自己的操作命名约定。请勿使用SDK客户端名称或IAM操作名称——这些会被拒绝。
无资源API密钥操作（推荐）：
服务AllowActionsAllowResources
地图
geo-maps:GetTile
, 
geo-maps:GetStaticMap
arn:aws:geo-maps:REGION::provider/default
地点
geo-places:Autocomplete
, 
geo-places:Geocode
, 
geo-places:ReverseGeocode
, 
geo-places:SearchText
, 
geo-places:SearchNearby
, 
geo-places:Suggest
, 
geo-places:GetPlace
arn:aws:geo-places:REGION::provider/default
路线
geo-routes:CalculateRoutes
, 
geo-routes:CalculateRouteMatrix
, 
geo-routes:CalculateIsolines
, 
geo-routes:OptimizeWaypoints
, 
geo-routes:SnapToRoads
arn:aws:geo-routes:REGION::provider/default
请勿使用旧版
geo:
前缀的操作（例如
geo:GetMap*
、
geo:CalculateRoute
）——这些仅适用于预先创建的资源，无法用于无资源API。

MCP Server Integration

MCP服务器集成

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.
与AWS MCP Server（Apache-2.0许可证）集成，该服务器提供AWS文档、API参考和直接API交互的访问权限。设置和凭证配置请参阅入门指南。要使用非默认区域，请在MCP配置参数中添加
"--metadata", "AWS_REGION=<your-region>"
。

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
根据特定实现需求加载以下资源：
  • 地址输入 - 创建高效的地址输入表单，通过地址输入提示完成功能提高输入速度和准确性
  • 地址验证 - 在执行操作或保存到数据库之前验证用户输入的地址
  • 路线计算 - 使用可自定义的出行选项计算地点间的路线并在地图上显示
  • 动态地图渲染 - 使用MapLibre渲染动态地图
  • 地点搜索 - 搜索地点或兴趣点
  • Web JavaScript - 在Web浏览器应用中集成Amazon Location服务