Nearby Search（新規）

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

欧州経済領域（EEA）のデベロッパー

請求先住所が欧州経済領域内にある場合は、2025 年 7 月 8 日より、 Google Maps Platform の EEA における利用規約 がこのサービスのご利用に適用されます。機能は地域によって異なります。詳細。

Nearby Search（新規）リクエストでは、検索する地域を円で指定します。円は、円の中心点の緯度と経度の座標と半径（メートル単位）で定義します。リクエストは、指定された検索エリア内の一致する場所のリストを返します。各場所は Place オブジェクトで表されます。

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

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

Nearby Search（新規）リクエスト

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

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

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

この Nearby Search リクエストの例では、レスポンスの Place オブジェクト に、検索結果の各 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);

// 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キャンセル リクエストが発行されると、レスポンスは返されません。 キャンセル トークンを発行しても、特定のリクエストがキャンセルされるとは限りません。レスポンスが返されなくても、リクエストの料金が請求される場合があります 。

Nearby Search（新規）レスポンス

The 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 Pro SKU をトリガーします。

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * サポート終了となった Place.Field.NAME の代わりに使用します。
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * サポート終了となった Place.Field.ICON_URL の代わりに使用します。
    Place.Field.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * サポート終了となった Place.Field.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.USER_RATINGS_TOTAL の代わりに使用します。
    Place.Field.WEBSITE_URI

  • 次のフィールドは、Nearby Search Enterprise Plus 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

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

  次の例では、リクエストによって返される Place オブジェクトに Place.Field.ID と Place.Field.DISPLAY_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.DISPLAY_NAME);

• ロケーションの制限

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

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

オプション パラメータ

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

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

  タイプ テーブル A のタイプのリストを指定して、検索結果をフィルタ できます。タイプ制限カテゴリごとに最大 50 個のタイプを指定できます。

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

  1 つの場所に関連付けることができるプライマリ タイプ は、タイプ テーブル 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 の場所タイプのリスト。 このパラメータを省略すると、すべてのタイプの場所が返されます。

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

  除外タイプ

  検索から除外するタイプ テーブル A の場所タイプのリスト。

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

  `includedTypes ` と `excludedTypes` の両方にタイプが表示されるなど、競合するタイプがある場合は、`INVALID_REQUEST` エラーが返されます。

  除外タイプ パラメータを設定するには、setExcludedTypes() メソッドを呼び出します。SearchNearbyRequest

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

  検索に含めるタイプ テーブル A のプライマリ場所タイプのリスト。

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

  除外プライマリ タイプ

  検索から除外するタイプ テーブル A のプライマリ場所タイプのリスト。

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

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

• 結果の最大数

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

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

• ランクの設定

  使用するランキングのタイプ。このパラメータを省略すると、結果は人気度順に並べ替えられます。 次のいずれかになります。

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

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

• 地域コード

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

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

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

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

アプリに属性を表示する

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

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