テキスト検索(新版)

Text Search (New) は、文字列に基づいて場所のセットに関する情報を返します。例: 「渋谷のピザ屋」、「新宿 2 丁目付近の靴店」、「中央通り 123」。サービスは、テキスト文字列と、設定された場所のバイアスに一致する場所のリストをレスポンスとして返します。

このサービスは、自動システムであいまいな住所のクエリを行う場合に特に有用です。文字列の住所以外の構成要素は、住所だけでなく企業や店舗とも一致します。あいまいな住所クエリの例としては、形式が不適切な住所や、ビジネス名などの住所以外の要素を含むリクエストなどがあります。次の表の最初の 2 つの例のようなリクエストでは、リージョン、ロケーション制限、ロケーション バイアスなどのロケーションが設定されていなければ、結果が 0 を返すことがあります。

「10 High Street, UK」または「123 Main Street, US」 英国には複数の「High Street」、米国には複数の「Main Street」があります。ロケーション制限が設定されていない場合、クエリから望ましい結果が返されません。
「チェーン レストラン ニューヨーク」 ニューヨークに複数の「ChainRestaurant」の場所がある。番地や通りの名前はない。
「10 High Street, Escher UK」または「123 Main Street, Pleasanton US」 英国のエッシャー市に「High Street」が 1 つだけ、米国カリフォルニア州プレザントンで「Main Street」が 1 つだけある。
「Unique レストラン Name New York」 この名前を持つニューヨークの施設は 1 つだけで、番地を区別する必要はありません。
"東京のピザ屋" このクエリには場所の制限が含まれており、「ピザ レストラン」は明確に定義された場所タイプです。複数の結果が返されます。
「+1 514-670-8700」

このクエリには電話番号が含まれています。その電話番号に関連付けられている場所について、複数の結果が返されます。

API Explorer を使用すると、ライブ リクエストを行って、API と API オプションについての理解を深めることができます。

試してみる

Text Search リクエスト

Text Search リクエストは、次の形式の HTTP POST リクエストです。

https://places.googleapis.com/v1/places:searchText

すべてのパラメータを JSON リクエスト本文またはヘッダーで POST リクエストの一部として渡します。次に例を示します。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Text Search(New)レスポンス

Text Search(新規)は JSON オブジェクトをレスポンスとして返します。レスポンスの説明:

  • places 配列には、一致するすべての場所が含まれます。
  • 配列内の各場所は Place オブジェクトで表されます。Place オブジェクトには、1 つの場所に関する詳細情報が含まれます。
  • リクエストで渡される FieldMask は、Place オブジェクトで返されるフィールドのリストを指定します。

完全な JSON オブジェクトの形式は次のとおりです。

{
  "places": [
    {
      object (Place)
    }
  ]
}

必須パラメータ

  • FieldMask

    レスポンス フィールド マスクを作成して、レスポンスで返すフィールドのリストを指定します。URL パラメータ $fields または fields を使用するか、HTTP ヘッダー X-Goog-FieldMask を使用して、レスポンス フィールド マスクをメソッドに渡します。レスポンスには、返されるフィールドのデフォルト リストはありません。フィールド マスクを省略すると、メソッドはエラーを返します。

    フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計上の方法です。これにより、不要な処理時間と課金を回避できます。

    返す場所データの種類をカンマ区切りのリストで指定します。たとえば、場所の表示名と住所を取得できます。

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    すべてのフィールドを取得するには、* を使用します。

    X-Goog-FieldMask: *

    以下のフィールドを 1 つ以上指定します。

    • 次のフィールドによって Text Search (ID Only) SKU がトリガーされます。

      places.id, places.name*

      * places.name フィールドには、場所のリソース名places/PLACE_ID の形式で含まれます。場所の名前のテキストにアクセスするには、places.displayName を使用します。
    • 次のフィールドによって Text Search(Basic)SKU がトリガーされます。

      places.accessibilityOptionsplaces.addressComponentsplaces.adrFormatAddressplaces.businessStatusplaces.displayNameplaces.formattedAddressplaces.googleMapsUriplaces.iconBackgroundColorplaces.iconMaskBaseUriplaces.locationplaces.photosplaces.plusCodeplaces.primaryTypeplaces.primaryTypeDisplayNameplaces.shortFormattedAddressplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport
    • 次のフィールドによって Text Search (Advanced) SKU がトリガーされます。

      places.currentOpeningHoursplaces.currentSecondaryOpeningHoursplaces.internationalPhoneNumberplaces.nationalPhoneNumberplaces.priceLevelplaces.ratingplaces.regularOpeningHoursplaces.regularSecondaryOpeningHoursplaces.userRatingCountplaces.websiteUri
    • 次のフィールドによって Text Search(Preferred)SKU がトリガーされます。

      places.allowsDogsplaces.curbsidePickupplaces.deliveryplaces.dineInplaces.editorialSummaryplaces.evChargeOptionsplaces.fuelOptionsplaces.goodForChildrenplaces.goodForGroupsplaces.goodForWatchingSportsplaces.liveMusicplaces.menuForChildrenplaces.parkingOptionsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.reviewsplaces.servesBeerplaces.servesBeerplaces.servesBeerplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
  • textQuery

    検索するテキスト文字列(例: 「レストラン」、「メイン ストリート 123」、「サンフランシスコのおすすめ場所」)。API はこの文字列と一致する候補を返し、関連性の高い順に結果を並べ替えます。

省略可能なパラメータ

  • includedType

    結果を、表 A で定義された指定タイプに一致する場所に制限します。指定できるタイプは 1 つのみです。次に例を示します。

    • "includedType":"bar"
    • "includedType":"pharmacy"
  • languageCode

    結果を返す言語。

    • サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
    • languageCode が指定されていない場合、API はデフォルトで en になります。無効な言語コードを指定すると、API から INVALID_ARGUMENT エラーが返されます。
    • この API は、ユーザーとローカルの双方が判読できる住所を提供するように最善を尽くします。この目的を達成するために、ローカル言語で番地を返し、必要に応じてユーザーが読み取れるスクリプトに文字変換して、優先言語を監視します。その他の住所はすべて優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントから選択された同じ言語で返されます。
    • 優先言語で名前を利用できない場合、API は最も近い言語を使用します。
    • 優先言語は、API が返す結果のセットや、返される順序にわずかな影響を及ぼします。ジオコーダは、言語によって略語の解釈方法が異なります。たとえば、通りの略語や、ある言語では有効な同義語は別の言語では使用できない同義語などがこれに該当します。
  • locationBias

    検索する領域を指定します。この場所はバイアスとして機能します。つまり、指定された場所の周辺にある結果(指定された領域外の結果を含む)を返すことができます。

    locationRestriction または locationBias を指定できます。両方は指定できません。locationRestriction は結果が存在するリージョンを指定するものと考えてください。locationBias は結果が存在するものの近くのリージョンを指定するもので、領域の外にあってもよいと考えてください。

    領域を長方形のビューポートまたは円として指定します。

    • 円は、中心点と半径(メートル単位)で定義されます。radius は 0.0 ~ 50000.0 の範囲で指定する必要があります。デフォルトの radius は 0.0 です。次に例を示します。

      "locationBias": {
        "circle": {
          "center": {
            "latitude": 37.7937,
            "longitude": -122.3965
          },
          "radius": 500.0
        }
      }
    • 長方形は緯度と経度のビューポートで、対角線上に並ぶ 2 つの最低点と最高点として表されます。低い点は長方形の南西の角、高い点は長方形の北東の角を表します。

      ビューポートは閉じた領域と見なされます。つまり、その境界も含まれます。緯度の境界は -90 ~ 90 度、経度の境界は -180 ~ 180 度の範囲内にする必要があります。

      • low = high の場合、ビューポートはその単一ポイントで構成されます。
      • low.longitude > high.longitude の場合、経度の範囲が反転します(ビューポートが 180 度の経度線と交差します)。
      • low.longitude = -180 度、high.longitude = 180 度の場合、ビューポートにはすべての経度が含まれます。
      • low.longitude = 180 度、high.longitude = -180 度の場合、経度の範囲は空になります。
      • low.latitude > high.latitude の場合、緯度の範囲は空になります。

      下限と上限の両方を入力する必要があります。表示されているボックスを空にすることはできません。空のビューポートはエラーになります。

      たとえば、次のビューポートはニューヨーク市を完全に囲んでいます。

      "locationBias": {
        "rectangle": {
          "low": {
            "latitude": 40.477398,
            "longitude": -74.259087
          },
          "high": {
            "latitude": 40.91618,
            "longitude": -73.70018
          }
        }
      }
  • locationRestriction

    検索する領域を指定します。指定された領域外の結果は返されません。領域を長方形のビューポートとして指定します。ビューポートの定義については、locationBias の説明をご覧ください。

    locationRestriction または locationBias を指定できます。両方は指定できません。locationRestriction は結果が存在するリージョンを指定するものと考えてください。locationBias は結果が存在するものの近くのリージョンを指定するもので、領域の外にあってもよいと考えてください。

  • maxResultCount

    返されるプレイスの結果の最大数を指定します。1 ~ 20(デフォルト)の値にする必要があります。

  • evOptions

    利用可能な電気自動車(EV)用充電コネクタと充電速度を識別するためのパラメータを指定します。

    • connectorTypes

      その場所で利用可能な EV 充電コネクタの種類でフィルタします。どのコネクタタイプもサポートしていない場所は除外されます。 サポートされている EV 充電コネクタのタイプには、AC 充電器と DC 充電器、Tesla の充電器、GB/T 準拠の充電器(中国の EV 急速充電用)、コンセント充電器などがあります。詳細については、リファレンス ドキュメントをご覧ください。

    • minimumChargingRateKw

      EV の最低充電速度(キロワット(kW)単位)で場所をフィルタします。最低充電速度より低い料金を請求する場所は除外されます。たとえば、充電速度が 10 kW 以上の EV 充電器を見つけるには、このパラメータを「10」に設定します。

  • minRating

    結果は、平均ユーザー評価がこの上限以上のもののみに限定されます。値は 0.0 ~ 5.0 の範囲で指定し、0.5 単位で指定します。例: 0、0.5、1.0、...、5.0(両端を含む)。値は 0.5 単位で切り上げられます。たとえば、値を 0.6 にすると、評価 1.0 未満の結果がすべて除外されます。

  • openNow

    true の場合、クエリが送信された時点で営業している場所のみを返します。false の場合、営業ステータスに関係なく、すべてのビジネスを返します。このパラメータを false に設定すると、Google プレイスのデータベースに営業時間が登録されていない場所が返されます。

  • priceLevels

    検索対象を特定の価格レベルでマークされている場所に限定します。デフォルトでは、すべての価格レベルが選択されます。

    PriceLevel で定義された 1 つ以上の値の配列を指定します。

    次に例を示します。

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
  • rankPreference

    レスポンスでの結果のランク付け方法を指定します。該当する場合、API はデフォルトで RELEVANCE を使用します。たとえば、「ニューヨーク市のレストラン」というクエリの場合、RELEVANCE がデフォルトです。「Mountain View, CA」などの地理的クエリやその他のタイプのクエリの場合、デフォルトは適用されず、結果はバックエンドで返された順序で表示されます。

    次の値があります。

    • DISTANCE: 距離で結果をランク付けします。
    • RELEVANCE: 関連性に基づいて結果をランク付けします。
  • regionCode

    レスポンスのフォーマットに使用するリージョン コード。 2 文字の CLDR コード値で指定します。このパラメータは、検索結果にバイアス効果を及ぼすこともできます。デフォルト値はありません。

    レスポンスの formattedAddress フィールドの国名が regionCode と一致する場合、formattedAddress から国コードが省略されます。このパラメータは、国名が使用可能な場合に常に含まれる adrFormatAddress や、shortFormattedAddress(国名が含まれない場合)には影響しません。

    ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」(.co.uk)ですが、ISO 3166-1 コードは「gb」(厳密には「グレート ブリテンおよび北アイルランド連合王国」の法人を意味します)です。パラメータは、適用される法律に基づいて結果に影響を与える可能性があります。

  • strictTypeFiltering

    includeType パラメータとともに使用します。true に設定すると、includeType で指定されたタイプに一致する場所のみが返されます。false の場合、デフォルトでは、指定したタイプと一致しない場所がレスポンスに含まれる可能性があります。

Text Search の例

クエリ文字列で場所を検索する

次の例は、「オーストラリアのシドニーのスパイシー ベジタリアン料理」という Text Search リクエストを示しています。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

X-Goog-FieldMask ヘッダーにより、レスポンスplaces.displayName,places.formattedAddress のデータ フィールドが含まれることが指定されています。レスポンスは次の形式になります。

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

フィールド マスクにデータ型を追加して、追加情報を返します。たとえば、places.types,places.websiteUri を追加して、レスポンスにレストラン タイプとウェブアドレスを含めます。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

レスポンスは次の形式になります。

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

価格帯で場所をフィルタ

「安い」または「やや高い」と評価されたレストランに結果をフィルタするには、priceLevel オプションを使用します。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

この例では、X-Goog-FieldMask ヘッダーを使用して places.priceLevel データ フィールドをレスポンスに追加し、次の形式にします。

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

includedTypeminRatingrankPreferenceopenNow や、オプション パラメータで説明されているその他のパラメータなど、検索を絞り込むためのオプションを追加します。

地域内で場所を検索する

検索範囲を 1 つのエリアに制限するには、locationRestriction または locationBias を使用します。両方は使用できません。locationRestriction は結果が存在するリージョンを指定するものと考えてください。locationBias は、結果が存在するものの近くのリージョンを指定するものと考えてください。ただし、領域の外にすることもできます。

次の例は、「スパイシー ベジタリアン料理」という Text Search リクエストで、サンフランシスコの繁華街の 500 m 以内の位置にバイアスがかかっていることを示しています。このリクエストでは、営業中の場所の検索結果のうち、最初の 10 件のみが返されます。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food",
  "openNow": true,
  "maxResultCount": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

最低充電速度の EV 充電器を検索する

minimumChargingRateKwconnectorTypes を使用して、EV と互換性のある充電器を使用できる場所を検索します。

次の例は、カリフォルニア州マウンテン ビューで、最小充電レート 10 kW の Tesla および J1772 Type 1 EV 充電コネクタのリクエストを示しています。結果は 4 つのみ返されます。

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "maxResultCount": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

このリクエストにより、次のレスポンスが返されます。

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

試してみよう:

API Explorer では、API と API オプションに慣れるためにサンプル リクエストを行うことができます。

  1. 必要に応じて、[標準パラメータを表示] を展開し、fields パラメータフィールド マスクに設定します。

  2. 必要に応じて、[Request body] を編集します。

  3. [Execute] ボタンを選択します。ポップアップ ダイアログ ボックスで、リクエストに使用するアカウントを選択します。