Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Maps Tools Resolution API

Maps Tools Resolution API は Maps Grounding Lite の一部です。場所の名前と Google マップの URL を Google マップのプレイス ID に解決するバッチエンドポイントを提供します。返されたプレイス ID は、他の Google Maps Platform API で使用できます。各レスポンスには、解決された場所を Google マップにリストとして保存するリンクも含まれています。

Resolution API は、REST メソッドと、Maps Grounding Lite MCP サーバーのツールとして利用できます。

能力	REST メソッド	MCP ツール
場所の名前または住所を場所に解決する	`resolveNames`	`resolve_names`
Google マップの URL を場所に解決する	`resolveMapsUrls`	`resolve_maps_urls`

始める前に

Resolution API を使用するには、課金が有効になっている Google Cloud プロジェクトと、Maps Grounding Lite API サービスが有効になっている必要があります。手順については、Google Cloud プロジェクトで Maps Grounding Lite サービスを有効にするをご覧ください。

API アクセスと認証

Resolution API は、API キーと OAuth 2.0 認証情報の両方をサポートしています。

API キー

リクエストを認証するには、有効な Google Maps Platform API キーを X-Goog-Api-Key ヘッダーで渡すか、リクエスト URL に追加します。

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

このページの例では、API_KEY を実際の API キーに置き換えてください。

OAuth 2.0 スコープ

OAuth 認証を使用する場合、次のスコープがサポートされます。

https://www.googleapis.com/auth/maps-platform.mapstools

使用量上限

Resolution API には、次のデフォルトの割り当てが適用されます。

ResolveNames: プロジェクトごとに 1 分あたり 600 クエリ。
ResolveMapsUrls: 1 プロジェクトあたり 1 分間に 600 クエリ。
バッチサイズ: リクエストごとに最大 20 個のクエリまたは URL。

各リクエストは、含まれるアイテムの数に関係なく、1 つのクエリとしてカウントされます。

料金

ResolveNames と ResolveMapsUrls へのリクエストは、Places API テキスト検索の基本事項（ID のみ） SKU で無料（$0）で課金されます。Maps Grounding Lite の他の機能と同様に、プロジェクトには請求先アカウントが必要です。

リクエストの検証と制約

過剰な負荷を防ぎ、迅速なレスポンス時間を確保するため、バッチリクエストは厳密に検証されます。

バッチサイズの上限: どちらの方法でも、リクエストごとに最大 20 個のアイテムを処理できます。
ResolveNames の要件:
- queries の各アイテムには、空でない text パラメータを指定する必要があります。
- クエリは、特定の場所の名前または住所（「Googleplex, Mountain View, CA」や「Eiffel Tower, Paris」など）を表す必要があります。
- 一般的なカテゴリ検索（「ニューヨークのレストラン」など）や、場所を指定しない一般的なチェーン名（「スターバックス」など）はサポートされておらず、解決できない場合があります。
ResolveMapsUrls の要件:
- 各 URL は、構造的に有効な Google マップの URL である必要があります。
- サポートされている形式:
  - 標準の場所の URL: https://www.google.com/maps/place/...
  - 短縮 URL: https://maps.app.goo.gl/...
- 一般的なクエリベースのマップ URL（https://maps.google.com/?q=restaurant など）と、単一の一意の場所を指していない URL はサポートされていません。

解決された場所を Google マップに保存する

バッチ内の少なくとも 1 つのアイテムが解決されると、レスポンスに saveToMapsUrl フィールドが含まれます。これは、バッチ内で正常に解決されたすべての場所を含む単一の Google マップのリンクです。解決された場所を Google マップでリストとして保存、共有、開くことを希望するユーザーに、このリンクを提示します。

必ず API から返されたリンクを使用してください。リンクを自分で作成しないでください。バッチ内のアイテムが解決されない場合、レスポンスに saveToMapsUrl は含まれません。

部分的なエラーを処理する

どちらの方法もバッチプロセッサです。バッチ内の一部のアイテムの解決に失敗しても、リクエスト全体がトップレベルのエラーで失敗することはありません。代わりに、API は部分的な成功レスポンスを返します。レスポンスでアイテムごとの失敗を確認する必要があります。

レスポンスを解釈する

1:1 の対応を保証: 返される results リスト（ResolveNames の場合）または entities リスト（ResolveMapsUrls の場合）は、インデックスによって入力リストと 1:1 で対応します。
失敗した要素は空: インデックス i のアイテムの解決に失敗した場合、結果リストのインデックス i には空のオブジェクト {} が含まれます。
failedRequests マップ: レスポンスには failedRequests マップが含まれます。
- キーは、失敗したアイテムの 0 ベースのインデックスです（JSON では文字列として表されます）。
- 値は、エラーコードと、アイテムが失敗した理由を説明するメッセージを含む google.rpc.Status オブジェクトです。
saveToMapsUrl は成功のみをカバーする: saveToMapsUrl リンクには、解決されたアイテムのみが含まれます。失敗したアイテムは含まれません。

1 つのアイテムが失敗したからといって、バッチ全体が失敗したとは限りません。解決できなかったアイテムがあるかどうかを確認するには、必ず failedRequests を確認してください。

アイテムごとのエラー

次の表に、failedRequests で表示される可能性のあるアイテムごとのエラーを示します。

メソッド	原因	コード	メッセージ
`ResolveNames`	名前または住所を場所に解決できません。	`5`（`NOT_FOUND`）	`Place not found.`
`ResolveMapsUrls`	URL を場所に解決できない。	`3`（`INVALID_ARGUMENT`）	`Failed to resolve Maps URL to a place.`
両方の方法	アイテムの解決中に内部エラーが発生しました。	`13`（`INTERNAL`）	`Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support`

INTERNAL で失敗したアイテムのみを再試行します。

トップレベルの障害

次の場合、API は部分的なレスポンスではなく、最上位のエラーを返します。

無効なリクエスト（400 INVALID_ARGUMENT）: リクエストに 20 個を超えるアイテムが含まれている、ResolveNames リクエストにクエリがない、または text 値が空のクエリがある、ResolveMapsUrls リクエストに空の URL がある、または構文的に有効な URL ではない。無効な項目が 1 つでもあると、リクエスト全体が失敗します。
認証、権限、割り当てのエラー: API キーがないか無効である、リクエストが使用量上限を超えている、など。
サーバーエラー（500 INTERNAL）: リクエストを再試行します。

MCP で Resolution API を使用する

https://mapstools.googleapis.com/mcp の Maps Grounding Lite MCP サーバーは、Resolution API を次の 2 つのツールとして公開します。

resolve_names: 複数の場所の名前または住所をプレイス ID に解決します。
resolve_maps_urls: Google マップの URL のバッチをプレイス ID に解決します。

Maps Grounding Lite MCP サーバーを使用するように LLM を構成すると、これらのツールを他の Maps Grounding Lite ツールとともに使用できます。これらのツールは、REST メソッドと同じ入力を受け入れ、同じ制約を適用し、同じ部分的な失敗レスポンスを返します。

ツールのレスポンスには save_to_maps_url フィールドが含まれます。ツールの説明では、ユーザーが解決された場所を Google マップにリストとして保存、共有、開くことを希望する場合、リンク自体を作成するのではなく、このリンクを提示するように LLM に指示します。

次の例では、curl を使用して resolve_names ツールを直接呼び出します。

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

resolve_maps_urls を呼び出すには、name を resolve_maps_urls に設定し、arguments に urls 配列を渡します。

REST API 仕様と curl の例

ResolveNames

メソッド: POST

https://mapstools.googleapis.com/v1:resolveNames

リクエスト本文の形式

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

queries（必須）: 解決するクエリの繰り返しリスト（最大 20）。
locationBias（省略可）: 結果をローカルリージョンにバイアスするためのビューポート境界ボックス。
regionCode（省略可）: 結果をバイアスする CLDR 国コード（「US」や「FR」など）。

curl の例: 解決成功

このクエリは「Googleplex」と「エッフェル塔」を解決します。

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON レスポンス

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

curl の例: 混合結果（部分的な失敗）

この例では、最初の項目は解決できないテキストで、2 番目の項目は有効な場所です。

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON レスポンス

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

メソッド: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

リクエスト本文の形式

{
  "urls": [
    "string"
  ]
}

urls（必須）: 解決する Google マップ URL 文字列の繰り返しリスト（最大 20 個）。

curl の例: 解決成功

次の例では、標準の Google マップの場所の URL を解決します。

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON レスポンス

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

curl の例: 混合結果（部分的な失敗）

次の例では、1 つの有効な場所 URL と、場所に解決できない 1 つの URL を解決します。

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON レスポンス

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

curl の例: 検証エラー

次の例では、1 回のリクエストで 20 個を超える URL を渡しています。

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON レスポンス

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

フィードバックを送信

Resolution API に関する問題を報告したり、フィードバックを共有したりするには、Maps Grounding Lite の公開 Issue Tracker コンポーネントを使用します。

Maps Tools Resolution API コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

API アクセスと認証

API キー

OAuth 2.0 スコープ

使用量上限

料金

リクエストの検証と制約

解決された場所を Google マップに保存する

部分的なエラーを処理する

レスポンスを解釈する

アイテムごとのエラー

トップレベルの障害

MCP で Resolution API を使用する

REST API 仕様と curl の例

ResolveNames

メソッド: POST

リクエスト本文の形式

curl の例: 解決成功

JSON レスポンス

curl の例: 混合結果（部分的な失敗）

JSON レスポンス

ResolveMapsUrls

メソッド: POST

リクエスト本文の形式

curl の例: 解決成功

JSON レスポンス

curl の例: 混合結果（部分的な失敗）

JSON レスポンス

curl の例: 検証エラー

JSON レスポンス

フィードバックを送信

Maps Tools Resolution API