amazon-location-service

概述

Amazon Location Service 提供用于地图、地理编码、路线规划、地点搜索、地理围栏和跟踪的地理空间 API。Web 开发优先使用捆绑的 JavaScript 客户端 (@aws/amazon-location-client)，并使用无资源 API 操作，避免管理 AWS 资源。

何时使用此技能

在以下情况下使用此技能：

• 构建具备位置感知能力的 Web 或移动应用
• 使用 Amazon Location Service 项目
• 实现地图、地理编码、路线规划或地点搜索
• 添加地理围栏或设备跟踪功能
• 将地理空间功能集成到 AWS 应用中

以下情况不要使用此技能：

• Google Maps、Mapbox 或使用 OSM 的 Leaflet 项目（迁移到 Amazon Location 时除外）
• 不涉及 AWS 的通用 GIS 操作
• 非 AWS 地理空间服务

Amazon Location Service API 概述

地点（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 凭证

常见错误

避免以下常见错误：

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 Map 构造函数中设置 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 风格的操作。完整列表请参阅“身份验证和权限”部分。

默认设置

除非用户明确提出其他要求，否则使用以下默认选项：

• JavaScript SDK：仅限浏览器的应用使用捆绑客户端（CDN）；React 和构建工具应用使用 npm 模块化 SDK（@aws-sdk/client-geo-*）
• API 操作：Maps/Places/Routes 使用无资源操作（Geofencing/Tracking 始终需要预先创建资源）
• 身份验证：Maps/Places/Routes 使用 API Key；Geofencing/Tracking 使用 Cognito
• 地图样式：Standard
• 坐标格式：[longitude, latitude]（GeoJSON 顺序）

覆盖默认设置：用户可以指定“Maps/Places/Routes 使用 Cognito”或“React 使用捆绑客户端”。

API 选择指南

根据你的使用场景选择合适的 API：

地址输入与验证

• Autocomplete → 用于地址表单中的输入联想（部分输入：“123 Main”）
• GetPlace → 用户选择自动补全结果后，获取完整详情（通过 PlaceId）
• Geocode → 验证用户输入的完整地址，或将地址转换为坐标

查找位置

• SearchText → 通用文本搜索（“西雅图附近的披萨店”）
• SearchNearby → 查找坐标附近的地点（5 公里内的餐厅）
• Suggest → 根据部分输入或拼写错误预测地点/POI
• Autocomplete → 地址专用预测（不用于通用 POI 搜索）

地理编码

• Geocode (Forward) → 地址字符串 → 坐标
• ReverseGeocode → 坐标 → 地址

地图

• Dynamic Maps (tiles + MapLibre) → 需要平移、缩放、标记的交互式地图
• Static Maps (image) → 用于缩略图或电子邮件的非交互式地图图片

路线规划

• CalculateRoutes → 起点与目的地之间的单条路线
• CalculateRouteMatrix → 多个起点/目的地之间的行程时间
• CalculateIsolines → 服务区域（在指定时间/距离内可到达的所有位置）

LLM 上下文文件

如果需要参考文件中未涵盖的详细 API 参数规范或服务能力，请获取以下 llms.txt 资源：

• 开发者指南：https://docs.aws.amazon.com/location/latest/developerguide/llms.txt
• API 参考：https://docs.aws.amazon.com/location/latest/APIReference/llms.txt

提供更好建议的关键指南

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

为方便开发 Web 应用，Amazon Location Service 提供了捆绑的 JavaScript 客户端，可简化集成并提供优化功能，无需自定义打包。此捆绑客户端包含使用 Amazon Location Service 构建客户端 Web 应用所需的所有库。

捆绑客户端包含的功能：

• 无需自定义打包/构建，即可直接引入预先打包的依赖项
• 简化身份验证和 API 集成
• 支持 TypeScript，并提供全面的类型定义
• 支持所有 Amazon Location SDK

包含的 SDK 和库：

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

资源：

• NPM 软件包： @aws/amazon-location-client
• GitHub 仓库：aws-geospatial/amazon-location-client-js

优先使用无资源操作

Amazon Location Places、Maps 和 Routes 服务同时提供基于资源和无资源的 API 操作。无资源操作通常更简单，也更适用于许多使用场景。

基于资源的操作要求你：

• 创建和配置 Amazon Location Service 资源（地图、地点索引、路线计算器）
• 管理资源生命周期和权限
• 处理资源命名和组织

无资源操作允许你：

• 直接进行 API 调用，无需预先创建资源
• 降低部署复杂性
• 简化 IAM 权限和 API Key 权限

身份验证和权限

讨论 Amazon Location Places、Maps 和 Routes 服务的权限时，务必在指南中同时包含 IAM 权限和 API Key 权限。如果明确了正在开发的应用类型，请按照下文所述推荐适当的授权工具：

IAM 权限 - 推荐用于服务端应用和 AWS SDK：

• 与 AWS 凭证（访问密钥、角色等）配合使用
• 提供精细的访问控制
• 资源管理操作必需

API Key 权限 - 替代身份验证方法，尤其适用于客户端应用，或部署给未通过身份验证的（公开）用户使用的应用：

• 简化身份验证，无需暴露 AWS 凭证
• 可配置特定的允许操作
• 适用于 Web 和移动应用
• 支持基于资源和无资源的操作
• 通过 CDN 缓存加快后续地图加载

API Key 操作名称 - API Key 使用自己的操作命名约定。请勿使用 SDK 客户端名称或 IAM 操作名称，否则请求会被拒绝。

无资源 API Key 操作（推荐）：

服务	AllowActions	AllowResources
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

请勿使用带有 geo: 前缀的旧版操作（例如 geo:GetMap*、geo:CalculateRoute）——这些操作仅适用于预先创建的资源，无法用于无资源 API。

MCP 服务集成

集成 AWS MCP Server（Apache-2.0 许可证），可访问 AWS 文档、API 参考和直接 API 交互。设置和凭证配置请参阅入门指南。要使用非默认区域，请在 MCP 配置参数中添加 "--metadata", "AWS_REGION=<your-region>"。

其他资源

• Amazon Location Service 开发人员指南
• Amazon Location Service API 参考
• Amazon Location Service 示例

参考文件

根据需要加载这些资源，获取具体的实现指导：

• 地址输入 - 为用户创建有效的地址输入表单，通过地址类型提前补全提升输入速度和准确性
• 地址验证 - 在执行操作或将用户输入的地址保存到数据库之前进行验证
• 路线计算 - 根据可自定义的出行选项计算地点之间的路线，并在地图上显示
• 动态地图渲染 - 使用 MapLibre 渲染动态地图
• 地点搜索 - 搜索地点或兴趣点
• Web JavaScript - 将 Amazon Location 服务集成到 Web 浏览器应用程序中