주변 검색(신규) 요청은 검색할 지역을 입력으로 사용합니다. 이 지역은 원의 중심점의 위도 및 경도 좌표와 반지름(미터)으로 정의된 원으로 지정됩니다. 요청은 지정된 검색 영역 내에서 일치하는 장소 목록을 반환하며, 각 장소는 Place 객체로 표시됩니다.
기본적으로 응답에는 검색 영역 내의 모든 유형의 장소가 포함됩니다. 선택적으로 응답에 명시적으로 포함하거나 제외할 장소 유형 목록을 지정하여 응답을 필터링할 수 있습니다. 예를 들어 '음식점', '빵집', '카페' 유형의 장소만 응답에 포함하거나 '학교' 유형의 장소는 모두 제외하도록 지정할 수 있습니다.
Nearby Search (신규) 요청
요청 매개변수를 정의하는 SearchNearbyRequest 객체를 전달하여 PlacesClient.searchNearby를 호출하여 Nearby Search (New) 요청을 합니다.
SearchNearbyRequest 객체는 요청에 필요한 모든 필수 매개변수와 선택적 매개변수를 지정합니다. 필수 매개변수는 다음과 같습니다.
Place객체에서 반환할 필드의 목록입니다(필드 마스크라고도 함). 필드 목록에 필드를 하나 이상 지정하지 않거나 필드 목록을 생략하면 호출에서 오류가 반환됩니다.- 검색 영역의 위치 제한입니다. 위도/경도 쌍과 반지름 값(미터)으로 정의됩니다.
이 예시 인근 검색 요청은 응답 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(); });
주변 지역 검색 (신규) 응답
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객체로 값 배열을 전달합니다. 필드 마스크를 사용하면 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.다음 필드 중 하나 이상을 지정합니다.
다음 필드는 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
필드 목록 매개변수를 설정하려면
SearchNearbyRequest객체를 빌드할 때setPlaceFields()메서드를 호출합니다.다음 예시에서는 요청에 의해 반환된
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보다 크고 50000.0 이하이어야 합니다. 반지름이 너무 작으면ZERO_RESULTS이 응답으로 반환됩니다.위치 제한 매개변수를 설정하려면
SearchNearbyRequest객체를 빌드할 때setLocationRestriction()메서드를 호출합니다.
선택적 매개변수
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의 장소 유형 목록입니다. 이 매개변수를 생략하면 모든 유형의 장소가 반환됩니다.
포함된 유형 매개변수를 설정하려면
SearchNearbyRequest객체를 빌드할 때setIncludedTypes()메서드를 호출합니다.제외된 유형
검색에서 제외할 표 A의 장소 유형 목록입니다.
요청에
includedTypes(예:"school")와excludedTypes(예:"primary_school")를 모두 지정하면 응답에"school"로 분류되지만"primary_school"로는 분류되지 않는 장소가 포함됩니다. 응답에는includedTypes중 하나 이상과 일치하고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' (기술적으로 '영국' 법인의 경우)입니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.
지역 코드 매개변수를 설정하려면
SearchNearbyRequest객체를 빌드할 때setRegionCode()메서드를 호출합니다.
앱에 특성 표시
앱에서 PlacesClient에서 가져온 정보(예: 사진, 리뷰)를 표시하는 경우, 앱은 필수 저작자 표시도 표시해야 합니다.
자세한 내용은 Android용 Places SDK 정책을 참고하세요.