Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

텍스트 검색(신규)

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

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

텍스트 검색 (신규)은 문자열 (예: '뉴욕의 피자', '오타와 근처의 신발 가게' 또는 '중앙로 123')을 기반으로 일련의 장소에 대한 정보를 반환하는 웹 서비스입니다. 이 서비스는 사전에 설정된 텍스트 문자열 및 특정 위치와 일치하는 장소의 목록을 반환합니다.

필수 매개변수 외에도 텍스트 검색 (신규)은 더 나은 결과를 위해 선택적 매개변수를 사용하여 쿼리 구체화를 지원합니다.

텍스트 검색 (신규)은 주변 검색 (신규)과 유사합니다. 두 가지의 주요 차이점은 텍스트 검색 (신규)을 사용하면 임의의 검색 문자열을 지정할 수 있지만 주변 지역 검색 (신규)에는 검색할 특정 영역이 필요하다는 것입니다.

텍스트 검색 요청

텍스트 검색 요청은 다음과 같은 형식입니다.

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

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

이 예에서는 다음을 수행합니다.

필드 목록을 Place.Field.ID 및 Place.Field.DISPLAY_NAME만 포함하도록 설정합니다. 즉, 일치하는 각 장소를 나타내는 응답의 Place 객체에는 이 두 필드만 포함됩니다.
SearchByTextRequest.Builder 를 사용하여 검색을 정의하는 SearchByTextRequest 객체를 만듭니다.
- 텍스트 쿼리 문자열을 'Spicy Vegetarian Food'로 설정합니다.
- 결과 장소의 최대 수를 10으로 설정합니다. 기본값과 최댓값은 20입니다.
- 검색 영역을 위도 및 경도 좌표로 정의된 직사각형으로 제한합니다. 이 영역 외부의 일치 항목은 반환되지 않습니다.
OnSuccessListener를 추가하고 SearchByTextResponse 객체에서 일치하는 장소를 가져옵니다.

참고: PlacesClient 초기화에 관한 자세한 내용은 Places API 클라이언트 초기화를 참고하세요.

텍스트 검색 응답

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

일치하는 모든 장소를 나타내는 Place 객체 목록(일치하는 장소당 하나의 Place 객체)
각 Place 객체에는 요청에 전달된 필드 목록으로 정의된 필드만 포함됩니다.

예를 들어 요청에서 필드 목록을 다음과 같이 정의했습니다.

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

이 필드 목록은 응답의 각 Place 객체에 일치하는 각 장소의 장소 ID와 이름만 포함됨을 의미합니다. 그런 다음 Place.getId() 및 Place.getName() 메서드를 사용하여 각 Place 객체의 이러한 필드에 액세스할 수 있습니다.

Place 객체의 데이터 액세스에 관한 자세한 예는 장소 객체 데이터 필드 액세스를 참고하세요.

페이지로 나누기

텍스트 검색의 SearchByTextResponse 클래스는 Pagination 객체를 반환하는 getPagination() 메서드를 통해 텍스트 검색 결과 페이지로 나누기에 액세스할 수 있도록 합니다.

Pagination 객체의 hasNextPage() 메서드를 사용하여 결과의 추가 페이지를 사용할 수 있는지 확인합니다. 이 메서드는 불리언 값 (true 또는 false)을 반환합니다.

hasNextPage()가 true를 반환하는 동안 fetchNextPage() 메서드를 호출하여 결과의 다음 페이지를 가져옵니다.

다음 예에서는 다음 페이지를 사용할 수 있는지 확인한 후 페이지를 로드하는 방법을 보여줍니다.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

자바

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

필수 매개변수

필수 매개변수는 SearchByTextRequest 다음과 같습니다.

필드 목록

반환할 장소 데이터 필드를 지정합니다. 반환할 데이터 필드를 지정하는 Place.Field 값 목록을 전달합니다. 응답에 반환된 필드의 기본 목록은 없습니다.

필드 목록은 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있는 좋은 설계 관행입니다.

다음 필드 중 하나 이상을 지정합니다.
- 다음 필드는 텍스트 검색 Essentials ID 전용 SKU를 트리거합니다.
  Place.Field.DISPLAY_NAME*
      * 버전 4.0에서 지원 중단된 Place.Field.NAME 대신 사용합니다.
  Place.Field.ID
  Place.Field.RESOURCE_NAME*
      * `places/PLACE_ID`places/PLACE_ID 형식으로 장소 리소스 이름을 포함합니다.
       DISPLAY_NAME을 사용하여 장소의 텍스트 이름에 액세스합니다.
  필드 및 연결된 SKU의 전체 목록은 장소 데이터 필드 (신규)를 참고하세요.
- 다음 필드는 텍스트 검색 Pro SKU를 트리거합니다.
  Place.Field.ACCESSIBILITY_OPTIONS*
      지원 중단된 Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE 대신 사용합니다.
  Place.Field.ADDRESS_COMPONENTS
  Place.Field.ADR_FORMAT_ADDRESS
  Place.Field.BUSINESS_STATUS
  Place.Field.FORMATTED_ADDRESS*
      지원 중단된 Place.Field.ADDRESS 대신 사용합니다.
  Place.Field.GOOGLE_MAPS_URI
  Place.Field.ICON_BACKGROUND_COLOR
  Place.Field.ICON_MASK_URL *
      지원 중단된 Place.Field.ICON_URL 대신 사용합니다.
  Place.Field.LOCATION*
      지원 중단된 Place.Field.LAT_LNG 대신 사용합니다.
  Place.Field.PHOTO_METADATAS
  Place.Field.PLUS_CODE
  Place.Field.PRIMARY_TYPE
  Place.Field.PRIMARY_TYPE_DISPLAY_NAME
  Place.Field.SHORT_FORMATTED_ADDRESS
  Place.Field.SUB_DESTINATIONS
  Place.Field.TYPES
  Place.Field.UTC_OFFSET
  Place.Field.VIEWPORT
  필드 및 연결된 SKU의 전체 목록은 장소 데이터 필드 (신규)를 참고하세요.
- 다음 필드는 텍스트 검색 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
  필드 및 연결된 SKU의 전체 목록은 장소 데이터 필드 (신규)를 참고하세요.
- 다음 필드는 텍스트 검색 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
  필드 및 연결된 SKU의 전체 목록은 장소 데이터 필드 (신규)를 참고하세요.
필드 목록 매개변수를 설정하려면 setPlaceFields() 객체를 빌드할 때 SearchByTextRequest 메서드를 호출합니다.

텍스트 쿼리

검색할 텍스트 문자열(예: '음식점', '중앙로 123' 또는 '샌프란시스코에서 방문하기 가장 좋은 장소'). API는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다.

텍스트 쿼리 매개변수를 설정하려면 setTextQuery() 메서드를 빌드할 때 SearchByTextRequest 객체를 호출합니다.

참고: 전화번호로 검색할 때 최상의 결과를 얻으려면 국가 코드를 포함하고 공백을 추가한 후 regionCode 매개변수를 국가 코드에 상응하도록 설정합니다. 전화번호 형식은 국가마다 다르며 API는 이러한 다양한 형식의 결과를 반환하려고 시도합니다. 유효한 전화번호의 경우 Places API (신규)는 E.164 형식을 지원합니다. 알파벳 문자는 E.161 키패드 매핑을 기반으로 변환됩니다.

선택적 매개변수

SearchByTextRequest 객체를 사용하여 요청의 선택적 매개변수를 지정합니다.

포함된 유형

표 A에 정의된 지정된 유형과 일치하는 장소로 결과를 제한합니다. 표 A. 유형은 하나만 지정할 수 있습니다. 예를 들면 다음과 같습니다.
- setIncludedType("bar")
- setIncludedType("pharmacy")
참고: 표 B의 값은 응답에서만 반환됩니다. 표 B 의 값을 필터로 사용할 수는 없습니다.

포함된 유형 매개변수를 설정하려면 setIncludedType() 메서드를 빌드할 때 SearchByTextRequest 객체를 호출합니다.
위치 상세 검색

검색할 영역을 지정합니다. 이 위치는 상세 검색 역할을 하므로 지정된 영역 외부의 결과를 포함하여 지정된 위치 주변의 결과를 반환할 수 있습니다.

위치 제한 또는 위치 상세 검색을 지정할 수 있지만 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 있어야 하는 리전을 지정하는 것으로, 위치 상세 검색은 결과가 있을 가능성이 높은 리전 또는 결과가 있을 가능성이 높은 리전 근처를 지정하는 것으로 생각하세요. 위치 상세 검색을 사용하는 경우 결과가 지정된 영역 외부에 있을 수도 있습니다.

참고: 위치 상세 검색과 위치 제한을 모두 생략하면 API는 기본적으로 IP 상세 검색을 사용합니다. IP 상세 검색을 사용하면 API는 기기의 IP 주소를 사용하여 결과를 상세 검색합니다.

참고: locationBias 매개변수는 textQuery에 Market in Barcelona와 같은 명시적 위치가 포함되어 있으면 재정의할 수 있습니다. 이 경우 locationBias는 무시됩니다.

영역을 직사각형 표시 영역 또는 원으로 지정합니다.
- 원은 중심점과 반지름(미터)으로 정의됩니다. 반지름 은 0.0 이상 50000.0 이하여야 합니다. 예를 들면 다음과 같습니다.
```
// Define latitude and longitude coordinates of the center of the search area.
LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);

// Use the builder to create a SearchByTextRequest object.
// Set the radius of the search area to 500.0 meters.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();
```
- 직사각형은 대각선으로 반대되는 두 개의 낮은 점과 높은 점으로 표시되는 위도-경도 표시 영역입니다. 낮은 점은 직사각형의 남서쪽 모서리를 표시하고 높은 점은 직사각형의 북동쪽 모서리를 나타냅니다.
  
  표시 영역은 경계를 포함하는 닫힌 영역으로 간주됩니다. 위도 경계 는 -90도 이상 90도 이하여야 하며 경도 경계 는 -180도 이상 180도 이하여야 합니다.
  - low = high인 경우 표시 영역은 단일 점으로 구성됩니다.
  - low.longitude > high.longitude인 경우 경도 범위가 반전됩니다 (표시 영역이 180도 경도선을 교차함).
  - low.longitude = -180도이고 high.longitude = 180도인 경우 표시 영역에 모든 경도가 포함됩니다.
  - low.longitude = 180도이고 high.longitude = -180도인 경우 경도 범위가 비어 있습니다.
  - low.latitude > high.latitude인 경우 위도 범위가 비어 있습니다.
  낮은 점과 높은 점 모두 채워야 하며 표시된 상자는 비워 둘 수 없습니다. 표시 영역이 비어 있으면 오류가 발생합니다.
  
  예를 들어 직사각형 표시 영역의 경우 텍스트 검색 요청을 참고하세요.
  
  위치 상세 검색 매개변수를 설정하려면 setLocationBias() 메서드를 호출할 때 SearchByTextRequest 객체를 빌드합니다.
위치 제한

검색할 영역을 지정합니다. 지정된 영역 외부의 결과는 반환되지 않습니다. 영역을 직사각형 표시 영역으로 지정합니다. 표시 영역 정의에 관한 정보는 위치 상세 검색 설명을 참고하세요.

위치 제한 또는 위치 상세 검색을 지정할 수 있지만 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 있어야 하는 리전을 지정하는 것으로, 위치 상세 검색은 결과가 있어야 하는 리전 근처를 지정하는 것으로 생각하세요. 결과가 영역 외부에 있을 수도 있습니다.

참고: 위치 상세 검색과 위치 제한을 모두 생략하면 API는 기본적으로 IP 상세 검색을 사용합니다. IP 상세 검색을 사용하면 API는 기기의 IP 주소를 사용하여 결과를 상세 검색합니다.

위치 제한 매개변수를 설정하려면 setLocationRestriction() 메서드를 빌드할 때 SearchByTextRequest 객체를 호출합니다.
최대 결과 수

반환할 장소 결과의 최대 수를 지정합니다. 1 이상 20 (기본값) 이하여야 합니다.

최대 결과 수 매개변수를 설정하려면 setMaxResultCount() 메서드를 SearchByTextRequest 객체를 빌드할 때 호출합니다.
최하 등급

결과를 평균 사용자 평점이 이 한도보다 크거나 같은 결과로만 제한합니다. 값은 0.0 이상 5.0 이하 (0.5씩 증가)여야 합니다. 예: 0, 0.5, 1.0, ... , 5.0(포함) 값은 가장 가까운 0.5로 반올림됩니다. 예를 들어 값이 0.6이면 평점이 1.0 미만인 모든 결과가 삭제됩니다.

최하 등급 매개변수를 설정하려면 setMinRating() 메서드를 빌드할 때 SearchByTextRequest 객체를 호출합니다.
지금 영업 중

true인 경우 쿼리가 전송된 시점에 영업 중인 장소만 반환합니다. `false`인 경우 영업 상태와 관계없이 모든 비즈니스를 반환합니다. 이 매개변수를 false로 설정하면 Google 지역 정보 데이터베이스에 영업시간을 지정하지 않은 장소가 반환됩니다.

지금 영업 중 매개변수를 설정하려면 setOpenNow() 메서드를 빌드할 때 SearchByTextRequest 객체를 호출합니다.
가격대

기본적으로 결과에는 모든 가격대에서 서비스를 제공하는 장소가 포함됩니다. 결과를 특정 가격대의 장소만 포함하도록 제한하려면 반환하려는 장소의 가격대에 해당하는 정수 값 목록을 전달하면 됩니다.
- 1 - 장소에서 저렴한 서비스를 제공합니다.
- 2 - 장소에서 적당한 가격의 서비스를 제공합니다.
- 3 - 장소에서 비싼 서비스를 제공합니다.
- 4 - 장소에서 매우 비싼 서비스를 제공합니다.
참고: 장소에서 무료 서비스를 제공함을 나타내는 정수 값 0, 응답에 포함될 수 있지만 요청에서 필터 값으로 사용할 수는 없습니다.

가격대 매개변수를 설정하려면 setPriceLevels() 메서드를 빌드할 때 SearchByTextRequest 객체를 호출합니다.
순위 환경설정

쿼리 유형에 따라 응답에서 결과의 순위를 지정하는 방법을 지정합니다.
- '뉴욕시의 음식점'과 같은 카테고리 쿼리의 경우 SearchByTextRequest.RankPreference.RELEVANCE (검색 관련성을 기준으로 결과 순위 지정)가 기본값입니다. 순위 환경설정을 SearchByTextRequest.RankPreference.RELEVANCE 또는 SearchByTextRequest.RankPreference.DISTANCE (거리를 기준으로 결과 순위 지정)로 설정할 수 있습니다.
- '캘리포니아 마운틴뷰'와 같은 비카테고리 쿼리의 경우 순위 환경설정 매개변수를 설정하지 않은 상태로 두는 것이 좋습니다.
순위 환경설정 매개변수를 설정하려면 setRankPreference() 메서드를 호출할 때 SearchByTextRequest 객체를 빌드합니다.
지역 코드

응답 형식을 지정하는 데 사용되는 지역 코드입니다. 두 글자로 된 CLDR 코드 값으로 지정됩니다. 이 매개변수는 검색 결과에 상세 검색 효과를 줄 수도 있습니다. 기본값은 없습니다.

응답의 주소 필드의 국가 이름이 지역 코드와 일치하면 주소에서 국가 코드가 생략됩니다.

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

지역 코드 매개변수를 설정하려면 setRegionCode() 메서드를 호출할 때 SearchByTextRequest 객체를 빌드합니다.
엄격한 유형 필터링

포함된 유형 매개변수와 함께 사용됩니다. true`true`로 설정하면 포함된 유형으로 지정된 지정된 유형과 일치하는 장소만 반환됩니다. false(기본값)인 경우 응답에 지정된 유형과 일치하지 않는 장소가 포함될 수 있습니다.

엄격한 유형 필터링 매개변수를 설정하려면 setStrictTypeFiltering() 메서드를 호출할 때 SearchByTextRequest 객체를 빌드합니다.

텍스트 검색(신규) 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

텍스트 검색 요청

텍스트 검색 응답

페이지로 나누기

Kotlin

자바

필수 매개변수

필드 목록

텍스트 쿼리

선택적 매개변수

포함된 유형

위치 상세 검색

위치 제한

최대 결과 수

최하 등급

지금 영업 중

가격대

순위 환경설정

지역 코드

엄격한 유형 필터링

텍스트 검색(신규)