amazon-location-service

概要

Amazon Location Service は、マップ、ジオコーディング、ルーティング、場所の検索、ジオフェンシング、トラッキングのための地理空間 API を提供します。ウェブ開発では同梱の JavaScript クライアント（@aws/amazon-location-client）を優先して使用し、AWS リソースの管理を避けるために、リソースを必要としない API 操作を使用してください。

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• 位置情報を活用するウェブアプリケーションやモバイルアプリケーションを構築する
• Amazon Location Service のプロジェクトに取り組む
• マップ、ジオコーディング、ルーティング、場所の検索を実装する
• ジオフェンシングやデバイスのトラッキング機能を追加する
• 地理空間機能を AWS アプリケーションに統合する

次の場合、このスキルは使用しないでください：

• Google Maps、Mapbox、または Leaflet と 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 を実行）を使用して、住所を一括で検証し、標準化します。座標だけでなく、ジオコードでは得られない郵便当局による判定（ValidationGranularity、Mailable/Locatable、コンポーネントごとの StatusDetail）も取得できます。対応地域は米国、カナダ、英国、オーストラリアのみです。他の国ではジオコードを使用してください。

マップ（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. 表示に Address.Label ではなく Title を使う：Autocomplete の結果では、必ず Address.Label を表示してください。Title フィールドはコンポーネントが逆順で表示される場合があり、ユーザー向けのテキストには適していません。

2. マップの初期化に GetStyleDescriptor API を使う：GetStyleDescriptor API を呼び出すのではなく、MapLibre に直接 URL（https://maps.geo.{region}.amazonaws.com/v2/styles/Standard/descriptor?key={apiKey}）を渡す必要があります。マップを適切に描画するには、直接 URL を使う方法が必要です。

3. MapLibre の設定で validateStyle: false を指定し忘れる：Amazon Location のスタイルを使ってマップの読み込みを高速化するため、MapLibre Map コンストラクターでは必ず validateStyle: false を設定してください。

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 キー、Geofencing／Tracking では Cognito（クライアント側）または SigV4／IAM（サーバー側）、Jobs API／Address Validation（StartJob／GetJob／ListJobs／CancelJob）では SigV4／IAM ロール。API キーで認証できるのは Maps／Places／Routes のみです。Geofencing、Tracking、Jobs の操作では使用できません。
• マップスタイル：Standard
• 座標形式：[経度、緯度]（GeoJSON の順序）

上書き：ユーザーは「Maps／Places／Routes で Cognito を使う」または「React でバンドル済みクライアントを使う」と指定できます。

API 選択のガイダンス

ユースケースに適した API を選んでください。

住所入力（インタラクティブなフォーム）

• Autocomplete → 住所フォームでの入力候補表示（部分入力：「123 Main」）
• GetPlace → ユーザーが Autocomplete の結果を選択した後に詳細を取得（PlaceId による）
• Geocode → ユーザーが入力した住所全体を座標に解決します。座標、一致したラベル、一致精度（全体およびコンポーネントごとの MatchScores、AddressNumberCorrected）を 1 回の同期呼び出しで返します。ただし、郵便物の配達可否の判定や標準化された出力はありません。

住所検証（検証と標準化）

• StartJob（Action ValidateAddress） → 信頼できる郵便データに基づいて住所を一括検証・標準化します。Amazon S3 の Parquet 入力／出力を使う非同期の Jobs API です。対応範囲：米国、カナダ、英国、オーストラリアのみ。それ以外の国では Geocode を使用してください。
• GetJob／ListJobs／CancelJob → 検証ジョブの追跡、一覧表示、キャンセル
• 郵便当局に基づく判定（ValidationGranularity、Mailable／Locatable、コンポーネントごとの StatusDetail）や一括処理のスループットが必要な場合は、Jobs API を選んでください。単一の住所が解決されるか、またどの程度一致するかをその場で確認する場合は、同期処理の Geocode MatchScores が適切なツールです。ジョブを立ち上げる必要はありません。住所検証のリファレンスを参照してください。

場所の検索

• SearchText → 一般的なテキスト検索（「Seattle 周辺のピザ」）
• SearchNearby → 座標周辺の場所を検索（5km 以内のレストラン）
• 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 キーの権限を簡素化する

認証と権限

Amazon Location の Places、Maps、Routes サービスの権限について説明する場合は、必ず IAM 権限と API キーの権限の両方を案内に含めてください。開発するアプリケーションの種類が明確な場合は、以下の説明に従って適切な認可方式を推奨してください。

IAM 権限 - サーバーサイドアプリケーションおよび AWS SDK の使用に推奨します。

• AWS 認証情報（アクセスキー、ロールなど）を使用します
• きめ細かなアクセス制御を提供します
• リソース管理操作に必要です

API キーの権限 - 代替の認証方式です。特にクライアントサイドアプリケーションや、認証されていない（パブリックな）ユーザー向けにデプロイするアプリケーションで役立ちます。

• AWS 認証情報を公開せずに、簡単に認証できます
• 許可する操作を指定して設定できます
• ウェブアプリケーションやモバイルアプリケーションに便利です
• リソースベースの操作とリソース不要の操作の両方に対応しています
• CDN キャッシュにより、2 回目以降の地図読み込みを高速化できます

Jobs API／住所検証、ジオフェンシング、トラッキング - これらの操作は API キーの対象外です。API キーで認証できるのは Maps、Places、Routes のみです。

• Jobs API／住所検証（Action ValidateAddress を指定した StartJob、GetJob、ListJobs、CancelJob）：サーバーサイド／バックオフィスの操作であり、IAM ロールまたは IAM ユーザーの認証情報に基づく SigV4 リクエスト署名を使用して呼び出す必要があります。API キーは使用できません。StartJob では ExecutionRoleArn（Amazon Location が S3 バケットの読み書きを行うために引き受ける別個の IAM ロール）も指定します。これは呼び出し元の ID に必要な SigV4／IAM 認証情報に加えて必要なものであり、その代わりにはなりません。住所検証のリファレンスを参照してください。
• ジオフェンシングとトラッキング：サーバーサイドの呼び出し元には SigV4／IAM を、クライアントサイド（ブラウザー／モバイル）の呼び出し元には Amazon Cognito ID プールを使用します。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 のドキュメント、API リファレンス、直接の API 呼び出しを利用できる AWS MCP Server（Apache-2.0 ライセンス）と統合します。セットアップと認証情報の設定については、Getting Started Guideを参照してください。デフォルト以外のリージョンを使用するには、MCP 設定の args に "--metadata", "AWS_REGION=<your-region>" を追加してください。

追加リソース

• Amazon Location Service 開発者ガイド
• Amazon Location Service API リファレンス
• Amazon Location Service サンプル

リファレンスファイル

具体的な実装方法が必要な場合は、以下のリソースを読み込んでください。

• 住所入力 - 住所の先行入力補完により入力速度と精度を向上させる、ユーザー向けの効果的な住所入力フォームを作成します
• 住所の検証 - データベースへの保存や後続の処理を行う前に、非同期の Jobs API（Action ValidateAddress を指定した StartJob）を使用して、信頼できる郵便データに照らし合わせて住所を一括検証し、標準化します
• ルートの計算 - カスタマイズ可能な移動オプションを使って地点間のルートを計算し、地図上に表示します
• デバイスのトラッキング - デバイスの位置をリアルタイムで追跡し、位置履歴を照会します
• 動的な地図のレンダリング - 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 のウェブアプリケーションを Google Maps API から Amazon Location Service に移行します
• 場所の検索 - 場所や興味のある地点を検索します
• Web JavaScript - Amazon Location のサービスをウェブブラウザーアプリケーションに統合します
• ゾーンアラート - 地理的な境界に対するデバイスの位置を監視し、ゾーンへの進入または退出に応じて処理を行います