Nearby Search(新規)

プラットフォームを選択: Android iOS JavaScript ウェブサービス

Nearby Search(新版)リクエストは 1 つ以上の場所タイプを受け取り、指定されたエリア内で一致する場所のリストを返します。1 つ以上のデータ型を指定するフィールド マスクが必要です。Nearby Search(新版)は POST リクエストのみをサポートしています。

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

試してみる

Nearby Search(新版)リクエスト

Nearby Search(新版)リクエストは、次の形式の URL に対する HTTP POST リクエストです。

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

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

Nearby Search(新版)の回答

Nearby 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 つ以上指定します。

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

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinations, places.adrFormatAddress, という形式の places.shortFormattedAddress, places.types を含む places.subDestinations, places.types、 という形式のplaces.nameplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID場所の名前のテキストにアクセスするには、places.displayName を使用します。

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

      places.currentOpeningHoursplaces.currentSecondaryOpeningHoursplaces.internationalPhoneNumberplaces.nationalPhoneNumberplaces.priceLevelplaces.ratingplaces.regularOpeningHoursplaces.regularSecondaryOpeningHoursplaces.userRatingCountplaces.websiteUri

    • 以下のフィールドで Nearby Search(Preferred)SKU がトリガーされます。

      places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, {2, , , /////}places.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • locationRestriction

    検索する地域を円として指定します。中心点と半径(メートル単位)で定義します。 半径は 0.0 ~ 50000.0 の範囲で指定してください。デフォルトの radius は 0.0 です。リクエストでは、0.0 より大きい値に設定する必要があります。

    次に例を示します。

    "locationRestriction": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

省略可能なパラメータ

  • includeTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

    検索結果のフィルタリングに使用する Table A タイプのリストを指定できます。各タイプ制限のカテゴリで最大 50 個のタイプを指定できます。

    場所には、関連付けられているタイプ Table A から 1 つのプライマリ タイプのみを指定できます。たとえば、プライマリ タイプは "mexican_restaurant""steak_house" です。includedPrimaryTypesexcludedPrimaryTypes を使用すると、場所のメインタイプに基づいて結果をフィルタリングできます。

    場所には、関連するタイプの Table A複数のタイプ値を含めることもできます。たとえば、レストランのタイプは "seafood_restaurant""restaurant""food""point_of_interest""establishment" です。includedTypesexcludedTypes を使用して、場所に関連付けられたタイプのリストの結果をフィルタリングします。

    複数のタイプ制限を指定して検索を指定した場合は、すべての制限を満たす場所のみが返されます。たとえば {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} を指定した場合、返される場所は "restaurant" 関連のサービスを提供しますが、主に "steak_house" として動作するわけではありません。

    includedTypes

    Table A から検索する場所タイプのカンマ区切りのリスト。 このパラメータを省略すると、すべてのタイプの場所が返されます。

    excludedTypes

    検索から除外する Table A の場所タイプのカンマ区切りリスト。

    リクエストで includedTypes"school" など)と excludedTypes"primary_school" など)の両方を指定した場合、レスポンスには "school" に分類されるが "primary_school" には分類されない場所が含まれます。レスポンスには、includedTypes の少なくとも 1 つに一致し、excludedTypes のいずれにも一致しない場所が含まれます。

    includedTypesexcludedTypes の両方に指定されているタイプなど、競合するタイプがある場合は、INVALID_REQUEST エラーが返されます。

    includedPrimaryTypes

    検索に含める、Table A の主要な場所タイプのカンマ区切りのリスト。

    excludedPrimaryTypes

    検索から除外する Table A のメインの場所タイプのカンマ区切りのリスト。

    includedPrimaryTypesexcludedPrimaryTypes の両方に存在するタイプなど、競合するプライマリ タイプが存在する場合は、INVALID_ARGUMENT エラーが返されます。

  • languageCode

    結果を返す言語。

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

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

  • rankPreference

    使用するランキングのタイプ。このパラメータを省略すると、結果は人気順でランク付けされます。次のいずれかになります。

    • POPULARITY(デフォルト)人気度に基づいて検索結果を並べ替えます。
    • DISTANCE 指定された場所からの距離に基づいて、結果を昇順で並べ替えます。
  • regionCode

    レスポンスのフォーマットに使用されるリージョン コード。 2 文字の CLDR コード値として指定します。デフォルト値はありません。

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

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

Nearby Search(新版)の例

同じ種類の場所を検索する

次の例は、半径 500 m 以内(circle で定義)内のすべてのレストランの表示名を Nearby Search(新版)リクエストする例を示しています。

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

さまざまな種類の場所を検索する

次の例は、指定した circle から半径 1,000 m 以内にあるすべてのコンビニエンス ストアと酒店の表示名を指定した Nearby Search(新版)リクエストを示しています。

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
この例では、フィールド マスクに places.primaryTypeplaces.types を追加して、レスポンスに各場所のタイプ情報が含まれるようにし、結果から適切な場所を選択しやすくしています。

次の例は、"primary_school" タイプのすべての場所を除外し、"school" タイプのすべての場所に対する Nearby Search(新版)リクエストを示しています。結果は距離に基づいてランク付けされます。

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

ある地域の付近のすべての場所を検索(距離でランク付け)

次の例は、サンフランシスコのダウンタウンの地点に近い場所を検索した Nearby Search(新版)リクエストを示しています。この例では、rankPreference パラメータを含めて、距離で結果をランク付けしています。

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

試してみよう:

API Explorer を使用すると、サンプル リクエストを作成して、API と API のオプションを把握できます。

  1. ページの右側にある API アイコン API Explorer を開きます。 を選択します。
  2. 必要に応じて、[標準パラメータを表示] を開き、fields パラメータフィールド マスクに設定します。
  3. 必要に応じて、[Request body] を編集します。
  4. [Execute] ボタンを選択します。ポップアップで、リクエストに使用するアカウントを選択します。
  5. [API Explorer] パネルで展開アイコン API Explorer を開きます。 を選択して、[API Explorer] ウィンドウを展開します。