Nearby Search(新規)

Nearby Search(New)リクエストでは、検索対象の領域を入力として受け取ります。この円は、円の中心点の緯度と経度の座標、および半径(メートル単位)で定義されます。このリクエストは、指定された検索領域内で、それぞれが Place オブジェクトで表される、一致する場所のリストを返します。

デフォルトでは、レスポンスには検索エリア内のすべてのタイプの場所が含まれます。プレイスタイプのリストを指定して、レスポンスに明示的に含める、またはレスポンスから除外するレスポンスをフィルタすることもできます。たとえば、「レストラン」、「パン屋」、「カフェ」タイプの場所のみをレスポンスに含めたり、「学校」タイプの場所をすべて除外したりするように指定できます。

Nearby Search(新規)リクエスト

PlacesClient.searchNearby を呼び出して Nearby Search(新規)リクエストを作成し、リクエスト パラメータを定義する SearchNearbyRequest オブジェクトを渡します。

SearchNearbyRequest オブジェクトは、リクエストの必須パラメータと省略可能なパラメータをすべて指定します。必須パラメータは次のとおりです。

  • Place オブジェクトに返すフィールドのリスト。フィールド マスクとも呼ばれます。フィールド リストでフィールドを 1 つも指定しなかった場合や、フィールド リストを省略すると、呼び出しでエラーが返されます。
  • 検索エリアの位置制限。緯度と経度のペアと半径の値(メートル単位)で定義されます。

この付近の検索リクエストの例では、レスポンスの Place オブジェクトに、検索結果の Place オブジェクトごとにプレイス フィールド Place.Field.IDPlace.Field.NAME が含まれていることが指定されています。また、「restaurant」と「cafe」というタイプの場所のみを返すレスポンスをフィルタし、「ピザ_restaurant」と「american_restaurant」タイプの場所は除外します。

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Nearby Search(New)のレスポンス

SearchNearbyResponse クラスは、検索リクエストからのレスポンスを表します。SearchNearbyResponse オブジェクトには次のものが含まれます。

  • 一致するすべての場所を表す Place オブジェクトのリスト。一致する場所ごとに 1 つの Place オブジェクトが含まれます。
  • Place オブジェクトには、リクエストで渡されたフィールド リストで定義されたフィールドのみが含まれます。

たとえば、このリクエストではフィールド リストを次のように定義します。

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

このフィールド リストでは、レスポンスの各 Place オブジェクトには、一致する各プレイスのプレイス ID と名前のみが含まれます。その後、Place.getId() メソッドと Place.getName() メソッドを使用して、各 Place オブジェクトのこれらのフィールドにアクセスできます。

Place オブジェクト内のデータにアクセスする例については、Place オブジェクトのデータ フィールドにアクセスするをご覧ください。

必須パラメータ

SearchNearbyRequest オブジェクトを使用して、検索に必要なパラメータを指定します。

  • フィールド リスト

    Place Details をリクエストするときは、その場所の Place オブジェクトで返すデータをフィールド マスクとして指定する必要があります。フィールド マスクを定義するには、Place.Field の値の配列を SearchNearbyRequest オブジェクトに渡します。不要なデータをリクエストしないようにするには、フィールド マスキングをおすすめします。これにより、不要な処理時間と課金を回避できます。

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

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

      Place.Field.ADDRESS_COMPONENTSPlace.Field.BUSINESS_STATUSPlace.Field.ADDRESSPlace.Field.ICON_BACKGROUND_COLORPlace.Field.ICON_URLPlace.Field.LAT_LNGPlace.Field.PHOTO_METADATASPlace.Field.PLUS_CODEPlace.Field.IDPlace.Field.NAMEPlace.Field.TYPESPlace.Field.UTC_OFFSETPlace.Field.VIEWPORTPlace.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
    • 次のフィールドによって Nearby Search(Advanced)SKU がトリガーされます。

      Place.Field.CURRENT_OPENING_HOURSPlace.Field.SECONDARY_OPENING_HOURSPlace.Field.PHONE_NUMBERPlace.Field.PRICE_LEVELPlace.Field.RATINGPlace.Field.OPENING_HOURSPlace.Field.USER_RATINGS_TOTALPlace.Field.WEBSITE_URI
    • 次のフィールドによって Nearby Search(Preferred)SKU がトリガーされます。

      Place.Field.CURBSIDE_PICKUPPlace.Field.DELIVERYPlace.Field.DINE_INPlace.Field.EDITORIAL_SUMMARYPlace.Field.RESERVABLEPlace.Field.REVIEWSPlace.Field.SERVES_BEERPlace.Field.SERVES_BREAKFASTPlace.Field.SERVES_BRUNCHPlace.Field.SERVES_DINNERPlace.Field.SERVES_LUNCHPlace.Field.SERVES_VEGETARIAN_FOODPlace.Field.SERVES_WINEPlace.Field.TAKEOUT

    フィールド リスト パラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setPlaceFields() メソッドを呼び出します。

    次の例では、リクエストによって返される Place オブジェクトに Place.Field.ID フィールドと Place.Field.NAME フィールドが含まれることを指定する 2 つのフィールド値のリストを定義します。

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
  • 地域の制限

    LocationRestriction オブジェクト。検索対象の領域を円で定義し、中心点と半径(メートル単位)で定義します。radius は 0.0 より大きく 50000.0 以下にする必要があります。小さすぎる半径を指定すると、レスポンスとして ZERO_RESULTS が返されます。

    ロケーション制限パラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setLocationRestriction() メソッドを呼び出します。

省略可能なパラメータ

SearchNearbyRequest オブジェクトを使用して、検索のオプション パラメータを指定します。

  • タイプと主なタイプ

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

    1 つの場所には、テーブル A タイプのメインタイプを 1 つのみ関連付けることができます。たとえば、メインのタイプは "mexican_restaurant""steak_house" です。includedPrimaryTypesexcludedPrimaryTypes を使用して、場所のメインのタイプで結果をフィルタリングします。

    1 つの場所に、Table A タイプの複数のタイプの値が関連付けられている場合もあります。たとえば、レストランが "seafood_restaurant""restaurant""food""point_of_interest""establishment" の各タイプを持つとします。includedTypesexcludedTypes を使用して、場所に関連付けられているタイプのリストの結果をフィルタリングします。

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

    includedTypesexcludedTypes の使用方法の例については、Nearby Search(新規)リクエストをご覧ください。

    含まれるタイプ

    検索対象の表 A の場所タイプのリスト。 このパラメータを省略すると、すべての型の桁数が返されます。

    含まれるタイプ パラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setIncludedTypes() メソッドを呼び出します。

    除外されるタイプ

    検索から除外する表 A の場所タイプのリスト。

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

    includedTypesexcludedTypes の両方に型が競合するなど、競合する型がある場合は、INVALID_REQUEST エラーが返されます。

    除外タイプのパラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setExcludedTypes() メソッドを呼び出します。

    含まれる主なタイプ

    検索に含める主な場所のタイプ(表 A)のリスト。

    含まれるメインのタイプのパラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setIncludedPrimaryTypes() メソッドを呼び出します。

    除外されるメインのタイプ

    検索から除外する表 A の主要な場所タイプのリスト。

    includedPrimaryTypesexcludedPrimaryTypes の両方に型が競合するなど、競合する型がある場合は、INVALID_ARGUMENT エラーが返されます。

    除外されるプライマリ タイプ パラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setExcludedPrimaryTypes() メソッドを呼び出します。

  • 最大結果数

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

    最大結果数パラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setMaxResultCount() メソッドを呼び出します。

  • ランク付けの設定

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

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

    ランク設定パラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setRankPreference() メソッドを呼び出します。

  • 地域コード

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

    レスポンスの formattedAddress フィールドの国名が regionCode と一致する場合、formattedAddress から国コードが省略されます。

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

    地域コード パラメータを設定するには、SearchNearbyRequest オブジェクトの作成時に setRegionCode() メソッドを呼び出します。

アプリに属性を表示する

アプリが PlacesClient から取得した情報(写真やレビューなど)を表示する場合、必要な属性も表示する必要があります。

詳しくは、Places SDK for Android のポリシーをご覧ください。