주변 검색 (신규)

플랫폼 선택: Android iOS JavaScript 웹 서비스

유럽 경제 지역 (EEA) 개발자

주변 지역 검색(신규) 요청은 검색할 리전을 입력으로 사용하며, 리전은 원의 중심점의 위도 및 경도 좌표와 반지름(미터)으로 정의된 원으로 지정됩니다. 요청은 지정된 검색 영역 내에서 일치하는 장소의 목록을 반환하며, 각 장소는 Place 객체로 표시됩니다.

기본적으로 응답에는 검색 영역 내의 모든 유형의 장소가 포함됩니다. 선택적으로 응답에 명시적으로 포함하거나 제외할 장소 유형 목록을 지정하여 응답을 필터링할 수 있습니다. 예를 들어 응답에 '음식점', '빵집', '카페' 유형의 장소만 포함하거나 '학교' 유형의 장소를 모두 제외하도록 지정할 수 있습니다.

주변 검색 (신규) 요청

요청 매개변수를 정의하는 SearchNearbyRequest 객체를 전달하여 PlacesClient.searchNearby를 호출하여 주변 지역 검색 (신규) 요청을 합니다.

SearchNearbyRequest 객체는 요청에 필요한 모든 필수 매개변수와 선택적 매개변수를 지정합니다. 필수 매개변수는 다음과 같습니다.

  • Place 객체에서 반환할 필드 목록으로, 필드 마스크라고도 합니다. 필드 목록에서 하나 이상의 필드를 지정하지 않거나 필드 목록을 생략하면 호출에서 오류가 반환됩니다.
  • 위도/경도 쌍 및 반지름 값(미터)으로 정의된 검색 영역의 위치 제한입니다.

이 주변 검색 요청 예에서는 응답 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();
    });

주변 검색 (신규) 응답

SearchNearbyResponse 클래스는 검색 요청의 응답을 나타냅니다. SearchNearbyResponse 객체에는 다음이 포함됩니다.

  • 일치하는 모든 장소를 나타내는 Place 객체 목록으로, 일치하는 장소당 하나의 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 객체의 데이터 액세스에 관한 자세한 예는 장소 객체 데이터 필드 액세스를 참고하세요.

필수 매개변수

SearchNearbyRequest 객체를 사용하여 검색에 필요한 매개변수를 지정합니다.

  • 필드 목록

    장소 세부정보를 요청할 때 장소의 Place 객체에서 반환할 데이터를 필드 마스크로 지정해야 합니다. 필드 마스크를 정의하려면 Place.Field 의 값 배열을 SearchNearbyRequest 객체에 전달합니다. 필드 마스크를 사용하면 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.

    다음 필드 중 하나 이상을 지정합니다.

    • 다음 필드는 주변 검색 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

    • 다음 필드는 주변 검색 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

    • 다음 필드는 주변 검색 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 필드가 포함되도록 지정하는 두 개의 필드 값 목록을 정의합니다.

// 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개의 유형을 지정할 수 있습니다.

    장소에는 유형 표 A의 단일 기본 유형 만 연결될 수 있습니다. 예를 들어 기본 유형은 "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를 사용하는 방법의 예는 주변 지역 검색 (신규) 요청을 참고하세요.

    포함된 유형

    검색할 표 A의 장소 유형 목록입니다. 이 매개변수를 생략하면 모든 유형의 장소가 반환됩니다.

    포함된 유형 매개변수를 설정하려면 setIncludedTypes() 메서드를 빌드할 때 SearchNearbyRequest 객체를 호출합니다.

    제외된 유형

    검색에서 제외할 표 A의 장소 유형 목록입니다.

    요청에서 includedTypes (예: "school")와 excludedTypes (예: "primary_school")를 모두 지정하면 응답에 "school"로 분류되지만 "primary_school"로는 분류되지 않는 장소가 포함됩니다. 응답에는 하나 이상의 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 객체를 빌드합니다.

  • 지역 코드

    응답 형식을 지정하는 데 사용되는 지역 코드로, 두 글자로 된 CLDR 코드 값으로 지정됩니다. 기본값은 없습니다.

    응답의 FORMATTED_ADDRESS 필드의 국가 이름이 regionCode와 일치하면 FORMATTED_ADDRESS에서 국가 코드가 생략됩니다.

    대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)이지만 ISO 3166-1 코드는 'gb'(엄밀히 말하면 '영국'의 항목)입니다. 이 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.

    지역 코드 매개변수를 설정하려면 setRegionCode() 메서드를 호출할 때 SearchNearbyRequest 객체를 빌드합니다.

앱에 특성 표시

앱에서 PlacesClient사진, 리뷰와 같은 `PlacesClient`에서 가져온 정보를 표시할 때는 앱에서 필수 특성도 표시해야 합니다.

자세한 내용은 Android용 Places SDK 정책을 참고하세요.