텍스트 검색

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

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

"10 High Street, UK" 또는 "123 Main Street, US" 영국에는 여러 개의 '고속도로'가, 미국에는 여러 개의 '중앙로'가 있습니다. 위치 제한을 설정하지 않으면 쿼리가 원하는 결과를 반환하지 않습니다.
"뉴욕의 체인 레스토랑" 뉴욕에 여러 'ChainRestaurant' 위치가 여러 개 있습니다. 상세 주소 또는 거리 이름은 넣지 않아도 됩니다.
"10 High Street, Escher UK" 또는 "123 Main Street, Pleasanton US" 영국 에셔에는 '하이 스트리트'가 1개만 있고, 미국 캘리포니아주 플레전턴시에는 '메인 스트리트'가 1개만 있습니다.
'UniqueRestaurantName New York' 뉴욕에 이 이름을 가진 시설은 하나만 있어야 하며, 상세 주소를 구별할 필요는 없습니다.
"서울의 피자 전문점" 이 쿼리에는 위치 제한이 포함되어 있으며 '피자 레스토랑'은 명확하게 정의된 장소 유형입니다. 여러 결과를 반환합니다.
'+1 514-670-8700'

이 쿼리에는 전화번호가 포함되어 있습니다. 이 전화번호와 연결된 장소에 관한 여러 결과를 반환합니다.

텍스트 검색 요청

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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.NAME만 포함하도록 필드 목록을 설정합니다. 즉, 일치하는 각 장소를 나타내는 응답의 Place 객체에는 이 두 필드만 포함됩니다.

  • SearchByTextRequest.Builder를 사용하여 검색을 정의하는 SearchByTextRequest 객체를 만듭니다.

    • 텍스트 쿼리 문자열을 'Spicy Vegetarian Food'로 설정합니다.

    • 결과 장소의 최대 수를 10으로 설정합니다. 기본값 및 최댓값은 20입니다.

    • 검색 영역을 위도와 경도 좌표로 정의된 직사각형으로 제한합니다. 이 지역 외부의 일치 항목은 반환되지 않습니다.

  • OnSuccessListener를 추가하고 SearchByTextResponse 객체에서 일치하는 장소를 가져옵니다.

텍스트 검색 응답

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

  • 일치하는 모든 장소를 나타내는 Place 객체의 목록(일치하는 장소당 하나의 Place 객체 포함)

  • 각 Place 객체에는 요청에 전달된 필드 목록에 의해 정의된 필드만 포함됩니다.

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

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

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

Place 객체의 데이터에 액세스하는 더 많은 예는 장소 객체 데이터 필드 액세스를 참고하세요.

필수 매개변수

  • 필드 목록

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

    필드 목록은 불필요한 데이터를 요청하지 않도록 하는 좋은 설계 방법이며, 이렇게 하면 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.

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

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

      Place.Field.ID, Place.Field.NAME

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

      Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

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

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

  • 텍스트 쿼리

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

선택적 매개변수

SearchByTextRequest.Builder의 메서드를 사용하여 이러한 매개변수를 설정합니다. 예를 들어 최대 결과 수를 설정하려면 SearchByTextRequest.Builder.setMaxResultCount()를 호출합니다.

  • 포함된 유형

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

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

  • 위치 편향

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

    위치 제한 또는 위치 바이어스를 지정할 수 있지만 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 포함되어야 하는 지역을 지정하는 것으로, 위치 편향은 결과가 근처에 있어야 하지만 이 지역 밖에 있을 수 있는 지역을 지정하는 것으로 생각하면 됩니다.

    지역을 직사각형 표시 영역 또는 원으로 지정합니다.

    • 원은 중심점과 반경(미터)으로 정의됩니다. 반경은 0.0 이상 50000.0 이하여야 합니다. 기본 반경은 0.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();

    • 직사각형은 대각선으로 반대되는 2개의 저점과 최고점으로 표시되는 위도-경도 표시 영역입니다. 최저점은 직사각형의 남서쪽 모서리를 나타내고, 최고점은 직사각형의 북동쪽 모서리를 나타냅니다.

      표시 영역은 닫힌 영역으로 간주되며 표시 영역 내에 경계가 포함됩니다. 위도 경계는 -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인 경우 위도 범위는 비어 있습니다.

      낮음과 높음 모두 채워야 하며, 표시된 상자는 비워 둘 수 없습니다. 표시 영역이 비어 있으면 오류가 발생합니다.

      예를 들어 직사각형 표시 영역은 텍스트 검색 요청을 참조하세요.

  • 위치 제한

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

    위치 제한 또는 위치 바이어스를 지정할 수 있지만 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 포함되어야 하는 지역을 지정하는 것으로, 위치 편향은 결과가 근처에 있어야 하지만 이 지역 밖에 있을 수 있는 지역을 지정하는 것으로 생각하면 됩니다.

  • 최대 결과 수

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

  • 최하 등급

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

  • 지금 영업 중

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

  • 가격 수준

    특정 가격 수준으로 표시된 장소로 검색을 제한합니다. 기본값은 모든 가격 수준을 선택하는 것입니다.

    다음 정수 값 중 하나 이상의 목록을 지정합니다.

    • 1~PRICE_LEVEL_INEXPENSIVE
    • 2~PRICE_LEVEL_MODERATE
    • 3~PRICE_LEVEL_EXPENSIVE
    • 4~PRICE_LEVEL_VERY_EXPENSIVE

  • 순위 환경설정

    응답에서 결과의 순위가 지정되는 방식을 지정합니다. 해당하는 경우 API는 기본적으로 RELEVANCE를 사용합니다. 예를 들어 '뉴욕의 레스토랑'과 같은 쿼리의 경우 RELEVANCE가 기본값입니다. 'Mountain View, CA' 또는 다른 유형의 쿼리와 같은 지역 쿼리의 경우 기본값이 적용되지 않으며 결과는 백엔드에서 반환된 순서대로 표시됩니다.

    여기에 표시되는 값은 다음과 같습니다.

    • SearchByTextRequest.RankPreference.DISTANCE: 거리를 기준으로 결과의 순위를 지정합니다.
    • SearchByTextRequest.RankPreference.RELEVANCE: 관련성에 따라 결과의 순위를 매깁니다.

  • 리전 코드

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

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

    대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 특별한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)인 반면 ISO 3166-1 코드는 'gb' (기술적으로 '영국 및 북아일랜드'의 엔티티)입니다. 매개변수는 관련 법률에 따라 결과에 영향을 줄 수 있습니다.

  • 엄격한 유형 필터링

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