場所を検索

search_places ツールを使用すると、LLM は自然言語クエリから Google マップ上の場所を検索できます。このツールは、一致する場所の AI 生成の概要を返します。要約で引用されている場所ごとに、プレイス ID、緯度と経度の座標、Google マップのリンク、帰属情報も返されます。

search_places は、MCP サーバーを介して、または searchText REST メソッドとして呼び出すことができます。このページでは、Pro オプションを含むリクエスト オプション、レスポンスの内容、リクエストの課金方法について説明します。完全なスキーマについては、search_places MCP リファレンスと searchText REST リファレンスをご覧ください。

リクエスト オプション

LLM は、ユーザーのリクエストとツールの説明に基づいて、ツールを呼び出すときにこれらのオプションを設定します。独自の指示を使用して、モデルが使用するオプションに影響を与えることができます。Pro の使用を制御するをご覧ください。

次の表に、search_places のリクエスト オプションを示します。

オプション 説明
text_query 必須。検索クエリ(例: coffee shops near Golden Gate Park)。クエリには、明確な位置情報が含まれている必要があります。または、リクエストに location_bias が含まれている必要があります。
location_bias 円(center とオプションの radius_meters、最大 50,000 m)。この円の範囲内の結果が優先されます。text_query で明示的なロケーションを指定している場合は、代わりにそのロケーションが使用されます。
language_code 要約の言語(en、ja など)。デフォルトは英語です。
region_code ユーザーの CLDR 地域コード(例: US)。地域固有の場所の名前に影響し、適用される法律に基づいて検索結果に影響する可能性があります。
page_size 返す場所の最大数。デフォルトは 5 です。6 ~ 10 の値は Pro オプションです。10 を超える値を指定すると、INVALID_ARGUMENT エラーが返されます。サービスが返す場所の数が、リクエストされた数よりも少ないことがあります。
include_extended_details true の場合、要約にはPlace Detailsが含まれます。これは Pro オプションです。デフォルトは false です。

Pro オプション

2 つのオプションで Maps Grounding Pro SKU を選択します。いずれかまたは両方を使用するリクエストは、Pro SKU で課金されます。

Pro オプション 用途
include_extended_details を true に設定 ユーザーのリクエストに、クチコミからの分析情報、メニューのハイライト、雰囲気、訪問者のヒントなど、Place Detailsが必要な場合。
page_size(6 ~ 10) お客様が 5 か所以上の場所を比較したいと考えている。

どちらのオプションも使用しないリクエスト(page_size が 1 ~ 5 のリクエストを含む)は、Essentials SKU で課金されます。

拡張された Place Details

ユーザーのリクエストに、次のような定性的な分析情報、リアルタイムの条件、特殊な属性が必要な場合は、include_extended_details を true に設定します。

  • レビュー投稿者の意見: レビューに基づく分析情報、顧客の感情、フィードバック。
  • 具体的なサービス: メニュー項目、料理、名物料理、飲料、ビジネスのハイライト。
  • 雰囲気: インテリア、美観、雰囲気、ムード。
  • 訪問者向けの実用的なヒント: 事前予約の必要性、予約なしでの入店ポリシー、待ち時間、混雑状況、駐車場、設備など。
  • 近接性: ユーザーが近くにあるものや最も近いものを尋ねた場合の、クエリの場所または location_bias の中心からの距離または移動時間。

要約の分析情報は、クエリと各場所で利用可能なデータによって異なります。すべてのタイプの分析情報がすべての回答に表示されるわけではありません。

通常の検索(料理や店舗の種類、住所、連絡先情報、営業時間、標準的な設備など)の場合は、false(デフォルト)のままにします。詳細なリクエストの完了には時間がかかります。

拡張された詳細によってレスポンスの構造が変更されることはありません。指定しない場合、要約では各場所が 1 ~ 2 文で説明されます。これにより、各場所について、クチコミの分析情報など、より多くの Google マップデータに基づく詳細な説明が表示されます。構造化された places エントリは、両方の SKU で同じです。

例

次の MCP リクエストでは、最大 8 件の場所の詳細情報をリクエストしています。Pro SKU で請求されます。

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

次の例では、同じリクエストを searchText REST メソッドに送信します。

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

API_KEY を API キーに置き換えます。

詳細情報がない場合、概要では各場所が 1 つまたは 2 つの文で説明されます。

Example Trattoria [0](4.6★(1,250)· 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$)キャンドルが灯る、居心地の良いダイニング ルーム。レビューでは、ロマンチックだが週末は騒がしいと書かれている。タリアテッレ アル ラグー、ブッラータ、ティラミスなどが人気です。予約をおすすめします。予約なしの場合、金曜日と土曜日の夜は 30 ~ 45 分ほど待つことがあります。路上駐車スペースは限られています。

レスポンス

レスポンスには、次のフィールドが含まれます。

  • summary: 検索結果の自然言語による要約。places のエントリにマッピングされる [0] などのゼロベースの引用が含まれる場合があります。
  • places[]: 要約で言及されている場所。各場所には次の情報が含まれます。
    • place: 場所のリソース名(places/{id} 形式)。
    • id: プレイス ID。他の Google Maps Platform API と組み合わせて、地図上に場所を表示するなどの用途に使用できます。
    • location: 場所の緯度 / 経度座標。
    • googleMapsLinks: 場所(placeUrl)、ルート(directionsUrl)、クチコミ(reviewsUrl)、写真(photosUrl)、クチコミの作成(writeAReviewUrl)の Google マップのリンク。
    • attribution: 場所とともに表示する必要がある帰属情報。帰属表示の要件をご覧ください。
  • contentToken: エージェント データ可視化トークン(プレビュー版)。Places UI キット を使用して、レスポンス内の場所を追加料金なしで表示できます。レスポンスに 1 つ以上の場所が含まれている場合に返されます。

レスポンスの構造は、SKU、MCP、REST のいずれでも同じです。フィールドの詳細については、search_places のリファレンスをご覧ください。

課金と割り当て

各 search_places リクエストは 1 つの課金対象イベントです。

Places UI キットを使用して search_places レスポンスから場所を表示する場合は、エージェント データ可視化トークン(プレビュー)を使用することで、Places UI キットのリクエストが課金されないようにできます。

search_places の割り当ては、プロジェクトごとに 1 分あたり 300 クエリで、両方の SKU で共有されます。料金については、メインの料金表とインドの料金表をご覧ください。