amazon-location-service

概要

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

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

次のような場合にこのスキルを使用してください。

• 位置情報に対応したウェブアプリケーションやモバイルアプリケーションを構築する場合
• Amazon Location Service のプロジェクトを扱う場合
• マップ、ジオコーディング、ルート検索、場所検索を実装する場合
• ジオフェンシングやデバイス追跡の機能を追加する場合
• AWS アプリケーションに地理空間機能を統合する場合

次の用途ではこのスキルを使用しないでください。

• Google Maps、Mapbox、または Leaflet-with-OSM のプロジェクト（Amazon Location への移行の場合を除く）
• AWS のコンテキストを伴わない一般的な GIS 操作
• AWS 以外の地理空間サービス

Amazon Location Service API の概要

Places（SDK：geo-places、JS：@aws-sdk/client-geo-places）

• ジオコーディング（順ジオコーディング／逆ジオコーディング）：住所を座標に、またその逆に変換します
• 検索（テキスト／近隣）：連絡先情報や営業時間を含む POI を検索します
• オートコンプリート：ユーザー入力に基づいて住所を予測します
• サジェスト：部分的な入力や誤字を含むユーザー入力に基づいて場所や POI を予測します
• Get Place：場所 ID によって場所の詳細を取得します

Jobs（SDK：location、JS：@aws-sdk/client-location）

• 住所検証：非同期の Jobs API（Action ValidateAddress を指定して StartJob を実行し、その後 GetJob／ListJobs／CancelJob を実行）を使って、住所を一括で検証し標準化します。Geocode では得られない、郵便当局による判定結果（ValidationGranularity、Mailable/Locatable、コンポーネントごとの StatusDetail）が得られ、座標だけではありません。対応範囲は米国、カナダ、英国、オーストラリアのみです。その他の国では Geocode を使用してください。

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）

• 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 Key、Geofencing／Tracking では Cognito
• マップスタイル：Standard
• 座標形式：[longitude, latitude]（GeoJSON の順序）

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

API 選択ガイド

ユースケースに合った API を選択してください。

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

• Autocomplete → 住所フォームでの入力候補表示（部分入力：「123 Main」）
• GetPlace → ユーザーがオートコンプリートの結果を選択した後に詳細情報を取得（PlaceId を指定）
• Geocode → ユーザーが入力した完全な住所を座標に変換します。座標、照合されたラベル、照合品質（全体およびコンポーネントごとの MatchScores、AddressNumberCorrected）を 1 回の同期呼び出しで返しますが、郵便物の配達可否の判定や標準化された出力は返しません。

住所の検証（確認と標準化）

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

場所の検索

• SearchText → 一般的なテキスト検索（「Seattle 近くのピザ」）
• SearchNearby → 座標の近くにある場所を検索（5 km 以内のレストラン）
• Suggest → 部分入力やスペルミスのある入力から場所／POI を予測
• Autocomplete → 住所に特化した候補表示（一般的な POI 検索には使用しない）

ジオコーディング

• ジオコード（フォワード） → 住所文字列 → 座標
• リバースジオコード → 座標 → 住所

マップ

• 動的マップ（タイル＋MapLibre） → パン、ズーム、マーカーが必要なインタラクティブマップ
• 静的マップ（画像） → サムネイルやメール向けの、操作できないマップ画像

ルーティング

• ルートを計算 → 出発地と目的地の間の単一ルート
• ルートマトリックスを計算 → 複数の出発地／目的地間の所要時間
• 等値線を計算 → サービスエリア（時間または距離内に到達できるすべての場所）

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 操作とリソース不要の API 操作の両方を提供しています。リソース不要の操作は、多くの場合、よりシンプルで、多くのユースケースに適しています。

リソースベースの操作では、次のことが必要です。

• Amazon Location Service のリソース（マップ、場所インデックス、ルート計算機）を作成して設定する
• リソースのライフサイクルとアクセス許可を管理する
• リソースの命名と整理を行う

リソース不要の操作では、次のことができます。

• リソースを事前に作成せずに API を直接呼び出す
• デプロイの複雑さを軽減する
• IAM アクセス許可と API キーのアクセス許可を簡素化する

認証と権限

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

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

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

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

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

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 との直接のやり取りを利用できます。セットアップと認証情報の設定については、Getting Started Guideを参照してください。デフォルト以外のリージョンを使用するには、MCP 設定の引数に "--metadata", "AWS_REGION=<your-region>" を追加してください。

その他のリソース

• Amazon Location Service Developer Guide
• Amazon Location Service API Reference
• Amazon Location Service Samples

リファレンスファイル

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

• 住所入力 - 住所の先行入力補完により入力速度と精度を向上させる、ユーザー向けの効果的な住所入力フォームを作成します
• 住所の検証 - データベースへの保存や後続の処理を行う前に、非同期の 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 のサービスをウェブブラウザーアプリケーションに統合します
• ゾーンアラート - 地理的な境界に対するデバイスの位置を監視し、ゾーンへの進入または退出に応じて処理を行います