Nearby Search（新規）

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

Nearby Search (New) リクエストは、円として指定された検索対象の地域を入力として受け取ります。この地域は、円の中心点の緯度と経度の座標と、半径（メートル単位）で定義されます。このリクエストは、指定された検索エリア内の一致するプレイスのリストを返します。各プレイスは Place オブジェクトで表されます。

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

注: 周辺検索（新規）は、Places SDK for Android バージョン 3.5.0 以降で利用できます。詳細については、SDK バージョンを選択するをご覧ください。バージョン 4.0.0 で追加された Kotlin API の使用方法については、リファレンスの概要をご覧ください。

Nearby Search（新規）リクエスト

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

SearchNearbyRequest オブジェクトには、リクエストの必須パラメータとオプション パラメータをすべて指定します。必須パラメータには次のものがあります。

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

この近くの検索リクエストの例では、レスポンスの Place オブジェクトに、検索結果の各 Place オブジェクトの場所フィールド Place.Field.ID と Place.Field.DISPLAY_NAME が含まれるように指定しています。また、レスポンスが「restaurant」と「cafe」のタイプのみの場所を返すようにフィルタし、「pizza_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.DISPLAY_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();
    });

注: PlacesClient の初期化について詳しくは、Places API クライアントを初期化するをご覧ください。

CancellationToken を使用して、任意のリクエストクラス（FetchPlaceRequest など）へのリクエストのキャンセルを試行できます。キャンセルはベスト エフォート ベースで実行されます。キャンセル リクエストが送信されると、レスポンスは返されません。キャンセル トークンを発行しても、特定のリクエストがキャンセルされるとは限りません。また、レスポンスが返されなくても、リクエストに対して料金が請求される場合があります。

Nearby Search（新版）のレスポンス

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 オブジェクトで指定する必要があります。フィールド マスクを定義するには、値の配列を Place.Field から SearchNearbyRequest オブジェクトに渡します。フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間と課金が発生するのを防ぐことができます。

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

  • 次のフィールドは、Nearby Search (Basic) SKU をトリガーします。

    Place.Field.ADDRESS_COMPONENTS、Place.Field.BUSINESS_STATUS、Place.Field.ADDRESS、Place.Field.ICON_BACKGROUND_COLOR、Place.Field.ICON_URL、Place.Field.LAT_LNG、Place.Field.PHOTO_METADATAS、Place.Field.PLUS_CODE、Place.Field.PRIMARY_TYPE、Place.Field.PRIMARY_TYPE_DISPLAY_NAME、Place.Field.ID、Place.Field.NAME、Place.Field.TYPES、Place.Field.UTC_OFFSET、Place.Field.VIEWPORT、Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • 次のフィールドは、Nearby Search (Advanced) SKU をトリガーします。

    Place.Field.CURRENT_OPENING_HOURS、Place.Field.CURRENT_SECONDARY_OPENING_HOURS、Place.Field.INTERNATIONAL_PHONE_NUMBER、Place.Field.NATIONAL_PHONE_NUMBER、Place.Field.OPENING_HOURS、Place.Field.PRICE_LEVEL、Place.Field.RATING、Place.Field.SECONDARY_OPENING_HOURS、Place.Field.USER_RATING_COUNT、Place.Field.WEBSITE_URI、
    
    注: Place.Field.PHONE_NUMBER フィールドと Place.Field.USER_RATINGS_TOTAL フィールドは、Places SDK for Android バージョン 4.0 で非推奨になりました。代わりに、それぞれ Place.Field.INTERNATIONAL_PHONE_NUMBER と Place.USER_RATING_COUNT を使用してください。

  • 次のフィールドは、Nearby Search (Preferred) SKU をトリガーします。

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  注: Places SDK for Android バージョン 4.0 では、いくつかのプレイスデータ フィールドの非推奨化と新しいフィールドの追加が行われました。詳しくは、Places SDK for Android 4.0 の新しい場所データフィールドに移行する をご覧ください。

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

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

// 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.DISPLAY_NAME);

• 地域の制限

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

  位置情報の制限パラメータを設定するには、SearchNearbyRequest オブジェクトを作成するときに setLocationRestriction() メソッドを呼び出します。

オプション パラメータ

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

• タイプとプライマリ タイプ

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

  注: 表 B の値はレスポンスでのみ返されます。テーブル B の値をフィルタとして使用することはできません。

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

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

  "restaurant" や "hotel" などの一般的なプライマリ タイプを指定すると、指定されたプライマリ タイプよりも具体的なプライマリ タイプの場所がレスポンスに含まれることがあります。たとえば、プライマリ タイプ "restaurant" を含めるように指定します。レスポンスには、"restaurant" というプライマリ タイプを持つ場所が含まれますが、"chinese_restaurant" や "seafood_restaurant" など、より具体的なプライマリ タイプを持つ場所も含まれます。

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

  リクエストから includedTypes、excludedTypes、includedPrimaryTypes、excludedPrimaryTypes を省略すると、検索では位置情報の制限範囲内のすべてのタイプの場所が返されます。

  includedTypes と excludedTypes の使用例については、Nearby Search（新版）リクエストをご覧ください。

  含まれるタイプ

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

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

  除外されるタイプ

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

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

  includedTypes と excludedTypes の両方に出現する型など、競合する型がある場合、INVALID_REQUEST エラーが返されます。

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

  含まれるプライマリ タイプ

  検索に含める表 A の主要なプレイスタイプのリスト。

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

  除外されるプライマリ タイプ

  検索から除外する表 A のプライマリ プレイスタイプのリスト。

  includedPrimaryTypes と excludedPrimaryTypes の両方に表示されるタイプなど、競合するプライマリ タイプがある場合、INVALID_ARGUMENT エラーが返されます。

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

• 最大結果数

  返される場所の結果の最大数を指定します。1 ～ 20（デフォルト）の値にする必要があります。

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

• ランクの設定

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

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

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

• 地域コード

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

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

  ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、その ISO 3166-1 コードは「gb」（厳密には「United Kingdom of Great Britain and Northern Ireland」のエンティティ）です。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。

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

アプリに属性を表示する

アプリに PlacesClient から取得した情報（写真やクチコミなど）を表示する場合、アプリには必要な帰属情報も表示する必要があります。

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