텍스트 검색(신규)

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

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

이 서비스는 자동화된 시스템에서 모호한 주소 쿼리를 할 때 특히 유용하며, 문자열에서 주소가 아닌 구성 요소는 사업체 및 주소와 일치할 수 있습니다. 예를 들어, 모호한 주소 쿼리는 형식이 잘못된 주소 또는 사업체 이름과 같이 주소가 아닌 구성 요소가 포함된 요청 등이 있습니다. 처음 두 가지 예와 같은 요청은 지역, 위치 제한, 위치 편향과 같은 위치가 설정되지 않는 한 결과를 반환하지 않을 수 있습니다.

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

'10 High Street, UK' 또는 '123 Main Street, US'	영국의 여러 'High Street', 미국의 여러 'Main Street' 위치 제한을 설정하지 않으면 쿼리에서 원하는 결과를 반환하지 않습니다.
'ChainRestaurant New York'	뉴욕에 여러 개의 'ChainRestaurant' 위치가 있지만 상세 주소나 도로 이름이 없습니다.
'10 High Street, Escher UK' 또는 '123 Main Street, Pleasanton US'	영국 에셔 시에는 'High Street'가 1개만 있고, 미국 캘리포니아 주 플레젠튼 시에는 'Main Street'가 1개만 있습니다.
"UniqueRestaurantName New York"	뉴욕에 이 이름의 시설이 하나만 있습니다. 구분하는 데 필요한 상세 주소가 없습니다.
"뉴욕 피자 레스토랑"	이 쿼리에는 위치 제한이 포함되어 있으며 '피자 전문점'은 잘 정의된 장소 유형입니다. 여러 결과를 반환합니다.
'[phone]'	이 쿼리에는 전화번호가 포함되어 있습니다. 해당 전화번호와 연결된 장소에 대한 여러 결과를 반환합니다. 참고: 전화번호를 검색할 때 최상의 결과를 얻으려면 국가 코드 뒤에 공백을 넣고 region code 매개변수를 국가 코드에 맞게 설정하세요.

참고: 텍스트 검색 (신규)은 Android용 Places SDK 버전 3.3.0 이상에서 사용할 수 있습니다. 자세한 내용은 SDK 버전 선택하기를 참고하세요. 버전 4.0.0에 추가된 Kotlin API 사용에 관한 자세한 내용은 참조 개요를 참고하세요.

텍스트 검색 요청

참고: 텍스트 검색은 Android용 Places SDK (신규)의 일부이며 Android용 Places SDK에서는 사용할 수 없습니다.

장소 텍스트 검색 요청의 형식은 다음과 같습니다.

// 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 클라이언트 초기화를 참고하세요.

CancellationToken을 사용하여 요청 클래스 (예: FetchPlaceRequest)에 대한 요청을 취소하려고 시도할 수 있습니다. 취소는 최선의 방식으로 이루어집니다. 취소 요청이 접수되면 응답이 반환되지 않습니다. 취소 토큰을 발행한다고 해서 특정 요청이 취소되는 것은 아닙니다. 응답이 반환되지 않더라도 요청에 대한 비용이 청구될 수 있습니다.

텍스트 검색 응답

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 객체의 데이터에 액세스하는 다른 예는 장소 객체 데이터 필드에 액세스를 참고하세요.

필수 매개변수

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

• 필드 목록

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

  필드 목록은 불필요한 데이터를 요청하지 않도록 하는 좋은 설계 방법으로, 불필요한 처리 시간과 결제 요금을 방지하는 데 도움이 됩니다.

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

  • 다음 필드는 Text Search (ID Only) SKU를 트리거합니다.

    Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME
    
    참고:

    • Place.Field.NAME 필드는 Android용 Places SDK 버전 4.0에서 지원 중단되었습니다. 대신 Place.Field.DISPLAY_NAME를 사용합니다.
    • RESOURCE_NAME 필드에는 장소 리소스 이름이 places/PLACE_ID 형식으로 포함됩니다. DISPLAY_NAME을 사용하여 장소의 텍스트 이름에 액세스합니다.

  • 다음 필드는 Text Search (Basic) SKU를 트리거합니다.

    Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, 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
    
    참고: Place.Field.ADDRESS, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE 필드는 Android용 Places SDK 버전 4.0에서 지원 중단되었습니다. 대신 Place.Field.FORMATTED_ADDRESS, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, Place.ACCESSIBILITY_OPTIONS를 사용합니다. Place.Field.ACCESSIBILITY_OPTIONS는 장소 세부정보 (신규)에만 사용할 수 있습니다.

  • 다음 필드는 Text 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 필드는 Android용 Places SDK 버전 4.0에서 지원 중단되었습니다. 대신 각각 Place.Field.INTERNATIONAL_PHONE_NUMBER 및 Place.USER_RATING_COUNT를 사용하세요.

  • 다음 필드는 Text 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
  참고: Android용 Places SDK 버전 4.0에서는 여러 장소 데이터 필드가 지원 중단되고 새 필드가 추가되었습니다. 자세한 내용은 Android용 Places SDK 4.0의 새 장소 데이터 필드로 이전 을 참고하세요.

  필드 목록 매개변수를 설정하려면 SearchByTextRequest 객체를 빌드할 때 setPlaceFields() 메서드를 호출합니다.

• 텍스트 쿼리

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

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

선택적 매개변수

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

• 포함된 유형

  표 A에 정의된 지정된 유형과 일치하는 장소로 결과를 제한합니다. 하나의 유형만 지정할 수 있습니다. 예를 들면 다음과 같습니다.

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  참고: 표 B의 값은 응답에서만 반환됩니다. 표 B의 값을 필터로 사용할 수 없습니다.

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

• 위치 편향

  검색할 영역을 지정합니다. 이 위치는 편향 역할을 합니다. 즉, 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다.

  위치 제한 또는 위치 편향을 지정할 수 있지만 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 포함되어야 하는 지역을 지정하는 것이고 위치 상세 검색은 결과가 포함되거나 근처에 있을 가능성이 높은 지역을 지정하는 것이라고 생각하면 됩니다. 위치 상세 검색을 사용할 때도 결과가 지정된 지역 외부에 있을 수 있다는 점에 유의하세요.

  참고: 위치 편향과 위치 제한을 모두 생략하면 API는 기본적으로 IP 편향을 사용합니다. IP 편향의 경우 API는 기기의 IP 주소를 사용하여 결과에 편향을 적용합니다.
  참고: textQuery에 Market in Barcelona와 같은 명시적 위치가 포함된 경우 locationBias 매개변수를 재정의할 수 있습니다. 이 경우 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보다 크면 위도 범위가 비어 있습니다.

    최솟값과 최댓값을 모두 채워야 하며, 표시된 상자는 비워 둘 수 없습니다. 뷰포트가 비어 있으면 오류가 발생합니다.

    직사각형 뷰포트의 예는 텍스트 검색 요청을 참고하세요.

    위치 편향 매개변수를 설정하려면 SearchByTextRequest 객체를 빌드할 때 setLocationBias() 메서드를 호출합니다.

• 위치 제한

  검색할 영역을 지정합니다. 지정된 영역 밖의 결과는 반환되지 않습니다. 영역을 직사각형 뷰포트로 지정합니다. 뷰포트를 정의하는 방법에 관한 자세한 내용은 위치 편향 설명을 참고하세요.

  위치 제한 또는 위치 편향을 지정할 수 있지만 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 포함되어야 하는 지역을 지정하는 것이고 위치 편향은 결과가 근처에 있어야 하지만 해당 지역 밖에 있을 수도 있는 지역을 지정하는 것이라고 생각하면 됩니다.

  참고: 위치 편향과 위치 제한을 모두 생략하면 API는 기본적으로 IP 편향을 사용합니다. IP 편향의 경우 API는 기기의 IP 주소를 사용하여 결과에 편향을 적용합니다.

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

• 최대 결과 수

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

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

• 최하 등급

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

  최소 평점 매개변수를 설정하려면 SearchByTextRequest 객체를 빌드할 때 setMinRating() 메서드를 호출합니다.

• 지금 영업 중

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

  지금 열기 매개변수를 설정하려면 SearchByTextRequest 객체를 빌드할 때 setOpenNow() 메서드를 호출합니다.

• 가격 수준

  기본적으로 모든 가격대에서 서비스를 제공하는 장소가 결과에 포함됩니다. 특정 가격 수준의 장소만 포함하도록 결과를 제한하려면 반환하려는 장소의 가격 수준에 해당하는 정수 값 목록을 전달하면 됩니다.

  • 1 - 저렴한 서비스를 제공하는 장소입니다.
  • 2 - 적당한 가격의 서비스를 제공하는 장소입니다.
  • 3 - 비용이 비싼 서비스를 제공하는 장소입니다.
  • 4 - 장소에서 매우 비싼 서비스를 제공합니다.
  참고: 장소에서 무료 서비스를 제공함을 나타내는 정수 값 0는 응답에 포함될 수 있지만 요청에서 필터 값으로 사용할 수는 없습니다.

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

• 순위 환경설정

  검색어 유형에 따라 응답에서 결과의 순위가 지정되는 방식을 지정합니다.

  • '뉴욕시 레스토랑'과 같은 카테고리 검색의 경우 기본값은 SearchByTextRequest.RankPreference.RELEVANCE (검색 관련성별 결과 순위 지정)입니다. 순위 환경설정을 SearchByTextRequest.RankPreference.RELEVANCE 또는 SearchByTextRequest.RankPreference.DISTANCE (거리별 순위 지정)으로 설정할 수 있습니다.
  • '캘리포니아 마운틴뷰'와 같이 카테고리가 아닌 검색어의 경우 순위 환경설정 매개변수를 설정하지 않는 것이 좋습니다.

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

• 지역 코드

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

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

  대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 몇몇 눈에 띄는 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)인 반면 ISO 3166-1 코드는 'gb'입니다(기술적으로 'Great Britain과 Northern Ireland 연방국' 엔터티). 이 매개변수는 관련 법규에 따라 결과에 영향을 줄 수 있습니다.

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

• 엄격한 유형 필터링

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

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