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」など）を表す必要があります。
    • 一般的なカテゴリ検索（「New York のレストラン」など）や、場所のない一般的なチェーン名（「Starbucks」など）はサポートされていません 。解決に失敗する可能性があります。
  • 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 は対象外 です。

部分的なエラーの処理

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

レスポンスを解釈する方法

  1. 1 対 1 のアライメントの保証 : 返される結果（ResolveNames の場合）または エンティティ（ResolveMapsUrls の場合）のリストは、入力リストと 1 対 1 でマッピングされます。
  2. 失敗した要素の空の要素: インデックス i のアイテムが解決に失敗した場合、 結果リストのインデックス i に空のオブジェクト {} が含まれます。
  3. failedRequests マップ: レスポンスには failedRequests マップが含まれます。
    • キー は、失敗したアイテムの 0 ベースのインデックスです（JSON では文字列として表されます）。
    • 値 は、特定のエラーコード（標準の 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」と「Eiffel Tower」を解決します。

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 を解決します。

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"
  }
}