amazon-location-service

概述

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

何时使用此技能

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

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

以下情况请勿使用此技能：

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

Amazon Location Service API 概述

地点（SDK：geo-places，JS：@aws-sdk/client-geo-places）

• 地理编码（正向/反向）：将地址转换为坐标，或将坐标转换为地址
• 搜索（文本/附近）：查找包含联系方式和营业时间信息的兴趣点
• 自动补全：根据用户输入预测地址
• 建议：根据不完整或拼写错误的用户输入，预测地点和兴趣点
• 获取地点：通过地点 ID 获取地点详情

作业（SDK：location，JS：@aws-sdk/client-location）

• 地址验证：通过异步 Jobs API 批量验证和规范化地址（使用 Action ValidateAddress 调用 StartJob，然后调用 GetJob/ListJobs/CancelJob）。它补充了 Geocode 所缺少的功能——由邮政主管机构给出的验证结果（ValidationGranularity、Mailable/Locatable、每个组件的 StatusDetail），而不仅仅是坐标。仅覆盖美国、加拿大、英国和澳大利亚；其他国家/地区请使用 Geocode。

地图（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 进行显示：在 Autocomplete 结果中，始终显示 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 Key 权限中的操作名称错误：API Key 的 AllowActions 使用 geo-maps:、geo-places:、geo-routes: 前缀（例如，geo-places:Geocode、geo-routes:CalculateRoutes）。请勿使用 SDK 客户端名称（@aws-sdk/client-geo-places）或 IAM 风格的操作。完整列表请参见 Authentication and Permissions 部分。

默认设置

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

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

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

API 选择指南

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

地址输入（交互式表单）

• Autocomplete → 在地址表单中提供输入联想（部分输入：“123 Main”）
• GetPlace → 用户选择自动补全结果后，按 PlaceId 获取完整详情
• Geocode → 将用户输入的完整地址解析为坐标。一次同步调用即可返回坐标、匹配标签和匹配质量（总体 MatchScores 及各组件的分数、AddressNumberCorrected），但不提供邮政投递判定或标准化输出。

地址验证（核验与标准化）

• StartJob（Action ValidateAddress） → 根据权威邮政数据批量核验并标准化地址；这是一个异步 Jobs API，输入和输出均为 Amazon S3 中的 Parquet 文件。覆盖范围：仅限 US、CA、UK、AU；其他国家/地区请使用 Geocode。
• GetJob / ListJobs / CancelJob → 跟踪、枚举和取消验证任务
• 需要邮政机构判定（ValidationGranularity、Mailable/Locatable、各组件的 StatusDetail）或批量处理时，请选择 Jobs API。若只需临时检查单个地址是否能解析以及匹配程度如何，应使用同步 Geocode MatchScores，无需创建任务。请参见地址验证参考文档。

查找地点

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

地理编码

• 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 密钥权限。如果能明确所开发应用的类型，请按下文所述推荐合适的授权工具：

IAM 权限 — 推荐用于服务器端应用和 AWS SDK 的使用场景：

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

API 密钥权限 — 一种替代身份验证方法，尤其适用于客户端应用或部署给未认证（公开）用户使用的应用：

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

Jobs API / 地址验证、地理围栏和跟踪 — 这些操作不支持使用 API 密钥。API 密钥仅用于 Maps、Places 和 Routes。

• Jobs API / 地址验证（StartJob，Action 为 ValidateAddress，以及 GetJob、ListJobs、CancelJob）：这些是服务器端/后台操作，必须使用由 IAM 角色或 IAM 用户凭证支持的 SigV4 请求签名调用，绝不能使用 API 密钥。StartJob 还需要 ExecutionRoleArn（Amazon Location 用来读取/写入 S3 存储桶的独立 IAM 角色）；此角色是在调用方的 SigV4/IAM 凭证之外额外需要的，不能替代这些凭证。请参阅地址验证参考。
• 地理围栏和跟踪：服务器端调用方使用 SigV4/IAM；客户端（浏览器/移动端）调用方则可使用 Amazon Cognito 身份池。不支持使用 API 密钥。

API 密钥操作名称 — API 密钥使用独有的操作命名约定。请勿使用 SDK 客户端名称或 IAM 操作名称，否则会被拒绝。

无资源 API 密钥操作（推荐）：

服务	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。

LocationClient 设置

地理围栏和跟踪使用 LocationClient（@aws-sdk/client-location）。这些是基于资源的操作——使用前必须创建资源（跟踪器、地理围栏集合）。

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 服务集成

集成 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 示例

参考文件

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

• 地址输入 - 创建高效的地址输入表单，通过地址类型预先补全功能提升用户的输入速度和准确性
• 地址验证 - 使用异步 Jobs API（StartJob，搭配 Action ValidateAddress）根据权威邮政数据批量验证和标准化地址，然后再将其保存到数据库或执行后续操作
• 路线计算 - 使用可自定义的出行选项计算地点之间的路线，并在地图上显示
• 设备追踪 - 实时追踪设备位置并查询位置历史记录
• 动态地图渲染 - 使用 MapLibre 渲染动态地图
• Google Maps 迁移（Android） - 将 Android 应用从 Google Maps SDK for Android 迁移到 Amazon Location Service
• Google Maps 迁移（iOS） - 将 iOS 应用从 Google Maps SDK for iOS 迁移到 Amazon Location Service
• Google Maps 迁移（JavaScript） - 将 JavaScript Web 应用从 Google Maps API 迁移到 Amazon Location Service
• 地点搜索 - 搜索地点或兴趣点
• Web JavaScript - 将 Amazon Location 服务集成到 Web 浏览器应用中
• 区域提醒 - 根据地理边界监控设备位置，并对进入或离开区域做出响应