Maps Tools Resolution API（試験運用版）

Maps Tools Resolution API は、位置名と URL を Google マップのプレイス ID に解決するためのバッチ処理エンドポイントを提供します。

API アクセスと認証

認証方法

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

1. API キー

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. OAuth 2.0 スコープ

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

  • https://www.googleapis.com/auth/maps-platform.mapstools（推奨）

リクエストの検証と制約

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

  • バッチサイズの上限: どちらの API も、リクエストごとに最大 20 個のアイテムを許可します。
  • ResolveNames の要件:
    • queries アイテムごとに、空でないテキスト パラメータを指定する必要があります。
    • クエリは、特定の場所の名前または住所（「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 は対象外です。

部分的なエラーの処理

どちらの API もバッチ プロセッサとして設計されています。バッチ内のアイテムの一部が解決に失敗した場合、リクエスト全体はトップレベルのエラーで失敗しません。代わりに、API は部分的な成功レスポンスを返します。

レスポンスの解釈方法

  1. 1 対 1 のアライメントが保証される: 返される結果（ResolveNames の場合）またはエンティティ（ResolveMapsUrls の場合）のリストは、入力リストと 1 対 1 でマッピングされます。
  2. 失敗した要素の空の要素: インデックス i のアイテムが解決されなかった場合、結果リストのインデックス i に空のオブジェクト {} が含まれます。
  3. failedRequests マップ: レスポンスには failedRequests マップが含まれます。
    • key は、失敗したアイテムの 0 ベースのインデックスです（JSON では文字列として表されます）。
    • value は、特定のエラーコード（標準の gRPC/HTTP ステータスから）と、失敗した理由を説明する詳細なメッセージを含む google.rpc.Status オブジェクトです。

最上位の障害

最上位の HTTP エラー（400 Bad Request など）は、リクエストの検証に失敗した場合（20 個を超えるアイテムを渡す場合や、必須フィールドが欠落している場合など）にのみ返されます。

API 仕様と Curl の例

1. ResolveNames API

メソッド: POST

https://mapstools.googleapis.com/v1alpha: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/v1alpha:resolveNames?key=KEY"
JSON Response
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

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/v1alpha:resolveNames?key=KEY"
JSON Response
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

メソッド: POST

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

リクエストの本文の形式

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

Curl の例: 解決に成功した場合

標準の Google マップの場所のリンクを解決します。

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Curl の例: 結果が混在している（部分的な失敗）

有効なプレイス URL と形式が正しくない 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

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/v1alpha:resolveMapsUrls?key=KEY"
JSON Response
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}