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 の概要

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

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

マップ（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 を使用しない：オートコンプリートの結果では、常に 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 → ユーザーが Autocomplete の結果を選択した後、PlaceId を使って詳細情報を取得
• Geocode → ユーザーが入力した住所全体を検証する、または住所を座標に変換する

場所の検索

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

ジオコーディング

• Geocode（順ジオコーディング） → 住所文字列から座標へ
• 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 キーのアクセス許可の両方を必ず案内に含めてください。開発するアプリケーションの種類が明確な場合は、以下の説明に従って適切な認証ツールを推奨してください。

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

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

API キーのアクセス許可 - 代替の認証方法であり、特にクライアントサイドアプリケーションや、認証されていない（一般公開されている）ユーザー向けにデプロイされるアプリケーションに適しています。

• AWS 認証情報を公開せずに、簡単に認証できます
• 許可する操作を個別に設定できます
• Web アプリケーションやモバイルアプリケーションに適しています
• リソースを使用する操作と、リソースを使用しない操作の両方に対応しています
• CDN キャッシュにより、後続の地図読み込みを高速化できます

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 では機能しません。

MCP サーバーとの連携

AWS のドキュメント、API リファレンス、API との直接的なやり取りへのアクセスを提供する AWS MCP Server（Apache-2.0 ライセンス）と連携します。セットアップと認証情報の設定については、Getting Started Guideを参照してください。デフォルト以外のリージョンを使用するには、MCP の設定引数に "--metadata", "AWS_REGION=<your-region>" を追加してください。

その他のリソース

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

参照ファイル

特定の実装ガイダンスが必要な場合は、これらのリソースを読み込んでください。

• 住所入力 - ユーザー向けに、入力速度と精度を向上させる住所の先行入力補完機能を備えた効果的な住所入力フォームを作成します
• 住所の検証 - 操作の実行やデータベースへの保存の前に、ユーザーが入力した住所を検証します
• ルートの計算 - カスタマイズ可能な移動オプションを使用して地点間のルートを計算し、地図上に表示します
• 動的な地図の描画 - MapLibre で動的な地図を描画します
• 場所の検索 - 場所や興味のある地点を検索します
• Web JavaScript - Amazon Location サービスを Web ブラウザーアプリケーションに統合します