SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场amazon-location-service

amazon-location-service

部署与运维

查看项目

更新于 10-14 09:07

技能介绍

用途

Amazon Location Service 提供地图、地理编码、路线规划、地点搜索、地理围栏和追踪等地理空间 API，本技能用于在 AWS 应用中集成这些位置能力。适用于构建位置感知的 Web 或移动应用、使用 Amazon Location Service 的项目，以及实现地图、地理编码、路线规划、地点搜索、地理围栏或设备追踪等功能。

不适用于：Google Maps、Mapbox 或 Leaflet-with-OSM 项目（除非迁移到 Amazon Location）、无 AWS 上下文的通用 GIS 操作、非 AWS 地理空间服务。

主要能力

Places（SDK：geo-places，JS：@aws-sdk/client-geo-places）：地理编码（正向/反向，地址与坐标互转）、搜索（文本/周边，含联系方式和营业时间）、自动补全（根据用户输入预测地址）、建议（根据部分或拼写错误的输入预测地点和兴趣点）、按 place ID 获取地点详情。

Maps（SDK：geo-maps，JS：@aws-sdk/client-geo-maps）：动态地图（使用瓦片与 MapLibre 渲染的交互式地图）、静态地图（预渲染的非交互式地图图片，适合嵌入网页或作缩略图）。

Routes（SDK：geo-routes，JS：@aws-sdk/client-geo-routes）：带交通与距离估算的路线计算、服务区/等时线创建、多起点/终点的矩阵计算、GPS 轨迹与路段对齐、路线优化（旅行商问题）。

Geofences 与 Trackers（SDK：location，JS：@aws-sdk/client-location）：地理围栏（检测进出地理边界）、追踪器（当前与历史设备位置追踪）。

API Keys（SDK：location，JS：@aws-sdk/client-location）：在不暴露 AWS 凭证的情况下向公共应用授予访问权限。

使用方式

默认选择（除非用户明确要求其他方式）：

  • 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 顺序）。

推荐使用随附的 JavaScript 客户端（@aws/amazon-location-client，NPM 包 @aws/amazon-location-client，GitHub 仓库 aws-geospatial/amazon-location-client-js）。该客户端包含：@aws-sdk/client-geo-maps、@aws-sdk/client-geo-places、@aws-sdk/client-geo-routes、@aws-sdk/client-location、@aws-sdk/credential-providers、amazon-location-utilities-auth-helper-js。其特点包括无需自定义打包/构建即可直接引入预打包依赖、简化认证与 API 集成、TypeScript 类型定义支持、支持所有 Amazon Location SDK。

优先使用无资源操作（resourceless）：无资源操作可直接调用 API，无需预创建资源，降低部署复杂度，简化 IAM 与 API Key 权限；而有资源操作需要创建和配置资源（地图、地点索引、路线计算器）、管理资源生命周期与权限、处理资源命名与组织。

API 选择指引：

  • 地址输入与校验：Autocomplete 用于地址表单的即输即查；GetPlace 用于用户选择自动补全结果后获取完整详情（按 PlaceId）；Geocode 用于校验用户输入的完整地址或地址转坐标。
  • 查找地点：SearchText 用于通用文本搜索；SearchNearby 用于按坐标查找附近地点；Suggest 用于根据部分或拼写错误输入预测地点/POI；Autocomplete 专用于地址预测（不用于通用 POI 搜索）。
  • 地理编码：Geocode（正向）地址字符串转坐标；ReverseGeocode 坐标转地址。
  • 地图：动态地图（瓦片 + MapLibre）用于需要平移、缩放、标记的交互式地图；静态地图（图片）用于缩略图或邮件等非交互场景。
  • 路线：CalculateRoutes 用于单条起点到终点路线；CalculateRouteMatrix 用于多起点/终点行程时间；CalculateIsolines 用于服务区。

认证与权限：涉及 Places、Maps、Routes 时，应同时包含 IAM 权限与 API Key 权限。IAM 权限适用于服务端应用和 AWS SDK 使用，配合 AWS 凭证，提供细粒度访问控制，资源管理操作必需。API Key 权限适用于客户端应用或面向未认证（公共）用户的应用，无需暴露 AWS 凭证，可配置特定允许操作，支持无资源与有资源操作，并可通过 CDN 缓存加快后续地图加载。

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

  • Maps：geo-maps:GetTile、geo-maps:GetStaticMap，AllowResources 为 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，AllowResources 为 arn:aws:geo-places:REGION::provider/default。
  • Routes：geo-routes:CalculateRoutes、geo-routes:CalculateRouteMatrix、geo-routes:CalculateIsolines、geo-routes:OptimizeWaypoints、geo-routes:SnapToRoads，AllowResources 为 arn:aws:geo-routes:REGION::provider/default。

不要使用旧版 geo: 前缀操作（如 geo:GetMap*、geo:CalculateRoute），它们仅用于预创建资源，无法与无资源 API 配合。

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 。

MCP Server 集成：可与 AWS MCP Server（Apache-2.0 许可）集成，获取 AWS 文档、API 参考及直接 API 交互。使用非默认区域时，在 MCP 配置参数中添加 "--metadata", "AWS_REGION=<your-region>"。

常见错误

  • 显示时使用 Title 而非 Address.Label：Autocomplete 结果始终显示 Address.Label，Title 字段可能以相反顺序显示组件，不适合面向用户的文本。
  • 使用 GetStyleDescriptor API 初始化地图：必须直接向 MapLibre 传 URL（https://maps.geo.{region}.amazonaws.com/v2/styles/Standard/descriptor?key={apiKey}），而不是调用 GetStyleDescriptor API。
  • MapLibre 配置中忘记 validateStyle: false：为加快 Amazon Location 样式的地图加载，始终在 MapLibre Map 构造函数中设置 validateStyle: false。
  • 混用有资源与无资源操作：尽可能优先使用无资源操作。
  • API 操作命名不一致：引用 API 时使用 service:Operation 格式（如 geo-places:Geocode、geo-maps:GetStyleDescriptor）；SDK 客户端使用 @aws-sdk/client-* 格式。
  • 未正确处理嵌套 Address 对象：GetPlace 返回的 Address 包含嵌套对象（Region.Code、Region.Name、Country.Code2 等），非扁平字符串。
  • API Key 权限中操作名错误：API key 的 AllowActions 使用 geo-maps:、geo-places:、geo-routes: 前缀，不要使用 SDK 客户端名（@aws-sdk/client-geo-places）或 IAM 风格操作。

适用场景

位置感知型 Web/移动应用、地图展示（交互式或静态）、地址输入与校验、地点与兴趣点搜索、地理编码与逆编码、路线计算与矩阵、服务区与等时线、GPS 轨迹对齐、路线优化、地理围栏与设备追踪、公共应用的 API Key 授权接入。

限制

不适用于 Google Maps、Mapbox、Leaflet-with-OSM（除非迁移到 Amazon Location）、无 AWS 上下文的通用 GIS、非 AWS 地理空间服务。Geofencing 与 Tracking 必须使用预创建资源，不能使用无资源操作。API Key 权限必须使用 geo- 前缀操作名，旧版 geo: 前缀操作无法与无资源 API 配合。