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 Text Search Essentials（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/...
- 一般的なクエリベースの Google マップの 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 ではない URL がある。無効な項目が 1 つでも含まれていると、リクエスト全体が失敗します。
認証、権限、割り当てのエラー: たとえば、API キーがないか無効である、リクエストが使用量の上限を超えているなど。
サーバーエラー（500 INTERNAL）: リクエストを再試行します。

MCP で Resolution API を使用する

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

resolve_names: 複数の地名または住所を Place ID に解決します。
resolve_maps_urls: Google マップの URL のバッチを Place ID に解決します。

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

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

次の例では、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 の例: 結果が混在している（部分的な失敗）

次の例では、有効なプレイス URL と、プレイスに解決できない URL を 1 つずつ解決しています。

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