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：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
• 地图样式：Standard
• 坐标格式：[longitude, latitude]（GeoJSON 顺序）

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

API 选择指南

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

地址输入（交互式表单）

• Autocomplete → 地址表单中的输入提示（部分输入：“123 Main”）
• GetPlace → 用户选择 Autocomplete 结果后获取完整详情（通过 PlaceId）
• Geocode → 将用户输入的完整地址解析为坐标。一次同步调用即可返回坐标、匹配标签和匹配质量（整体及各组成部分的 MatchScores、AddressNumberCorrected），但不会提供地址是否可投递的判定或标准化输出。

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

• StartJob（操作 ValidateAddress） → 根据权威邮政数据批量核验并标准化地址；这是一个使用 Amazon S3 中 Parquet 输入/输出的异步 Jobs API。覆盖范围仅限 US、CA、UK、AU；其他国家/地区请使用 Geocode。
• GetJob / ListJobs / CancelJob → 跟踪、列出和取消验证任务
• 如果需要邮政机构的判定结果（ValidationGranularity、Mailable/Locatable、各组成部分的 StatusDetail）或批量处理能力，请选择 Jobs API。若只需临时检查单个地址能否解析以及匹配程度，同步 Geocode 返回的 MatchScores 就是合适的工具——不要创建任务。请参见地址验证参考。

查找地点

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

地理编码

• 地理编码（正向） → 地址字符串 → 坐标
• ReverseGeocode → 坐标 → 地址

地图

• 动态地图（瓦片 + MapLibre） → 需要平移、缩放和标记的交互式地图
• 静态地图（图像） → 用于缩略图或电子邮件的非交互式地图图像

路线规划

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

LocationClient 设置

Geofencing 和 Tracking 使用 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 交互。有关设置和凭证配置，请参阅入门指南。若要使用非默认区域，请将 "--metadata", "AWS_REGION=<your-region>" 添加到 MCP 配置参数中。

其他资源

• 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 浏览器应用中
• 区域提醒 - 根据地理边界监控设备位置，并对进入或离开区域做出响应