Wyszukaj tekst (nowa funkcja)

Wybierz platformę: Android iOS JavaScript Web Service

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wyszukiwanie tekstowe (nowe) zwraca informacje o zbiorze miejsc na podstawie ciągu znaków (np. „pizza w Krakowie”, „sklepy obuwnicze w pobliżu Warszawy” lub „ul. Nowa 123”). Usługa odpowiada listą miejsc pasujących do ciągu tekstowego i wszelkich ustawionych preferencji lokalizacji.

Oprócz wymaganych parametrów, wyszukiwanie tekstowe (nowe) umożliwia doprecyzowanie zapytań za pomocą opcjonalnych parametrów, aby uzyskać lepsze wyniki.

Wyszukiwanie tekstowe (nowe) jest podobne do wyszukiwania w pobliżu (nowego). Główna różnica między nimi polega na tym, że wyszukiwanie tekstowe (nowe) umożliwia określenie dowolnego ciągu wyszukiwania, a wyszukiwanie w pobliżu (nowe) wymaga podania konkretnego obszaru, w którym ma się odbywać wyszukiwanie.

Żądania wyszukiwania tekstowego

Żądanie wyszukiwania tekstowego ma postać:

// 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();
    });

W tym przykładzie:

  • Ustaw listę pól tak, aby zawierała tylko Place.Field.ID i Place.Field.DISPLAY_NAME. Oznacza to, że obiekty Place w odpowiedzi, które reprezentują każde pasujące miejsce, zawierają tylko te 2 pola.

  • Użyj SearchByTextRequest.Builder aby utworzyć obiekt SearchByTextRequest definiujący wyszukiwanie.

    • Ustaw ciąg zapytania tekstowego na „Spicy Vegetarian Food”.

    • Ustaw maksymalną liczbę miejsc w wynikach na 10. Wartość domyślna i maksymalna to 20.

    • Ogranicz obszar wyszukiwania do prostokąta zdefiniowanego przez współrzędne szerokości i długości geograficznej. Nie są zwracane żadne dopasowania poza tym obszarem.

  • Dodaj OnSuccessListener i pobierz pasujące miejsca z SearchByTextResponse obiektu.

Odpowiedzi wyszukiwania tekstowego

Klasa SearchByTextResponse reprezentuje odpowiedź na żądanie wyszukiwania. Obiekt SearchByTextResponse zawiera:

  • Listę obiektów Place, które reprezentują wszystkie pasujące miejsca, przy czym każdy obiekt Place odpowiada jednemu pasującemu miejscu.

  • Każdy obiekt Place zawiera tylko pola zdefiniowane przez listę pól przekazaną w żądaniu.

Na przykład w żądaniu zdefiniowano listę pól w ten sposób:

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

Ta lista pól oznacza, że każdy obiekt Place w odpowiedzi zawiera tylko identyfikator miejsca i nazwę każdego pasującego miejsca. Następnie możesz użyć metod Place.getId() i Place.getName(), aby uzyskać dostęp do tych pól w każdym obiekcie Place.

Więcej przykładów uzyskiwania dostępu do danych w obiekcie Place znajdziesz w artykule Dostęp do pól danych obiektu Place

Podział na strony

Klasa SearchByTextResponse wyszukiwania tekstowego umożliwia dostęp do podziału na strony wyników wyszukiwania tekstowego za pomocą metody getPagination(), która zwraca obiekt Pagination.

Użyj metody hasNextPage() obiektu Pagination, aby sprawdzić, czy dostępne są dodatkowe strony wyników. Ta metoda zwraca wartość logiczną (true lub false).

Gdy hasNextPage() zwraca wartość true, wywołaj metodę fetchNextPage(), aby pobrać następną stronę wyników.

Poniższy przykład pokazuje, jak sprawdzić, czy dostępna jest następna strona, a następnie ją wczytać.

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();
        }
}

Java

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
    }
  });

Wymagane parametry

Wymagane parametry SearchByTextRequest to:

  • Lista pól

    Określ, które pola danych miejsca mają być zwracane. Przekaż listę Place.Field wartości określających pola danych, które mają być zwracane. W odpowiedzi nie ma domyślnej listy zwracanych pól.

    Listy pól to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

    Określ co najmniej jedno z tych pól:

    • Te pola powodują wywołanie jednostki SKU Wyszukiwanie tekstowe – podstawowe (tylko identyfikator):

      Place.Field.DISPLAY_NAME*
          * Użyj zamiast Place.Field.NAME (wycofane w wersji 4.0).
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * Zawiera nazwę zasobu miejsca w formacie: places/PLACE_ID.
      Użyj DISPLAY_NAME, aby uzyskać dostęp do nazwy tekstowej miejsca.

      Pełną listę pól i powiązanych z nimi jednostek SKU znajdziesz w artykule Pola danych miejsca (nowe).

    • Te pola powodują wywołanie jednostki SKU Wyszukiwanie tekstowe – wersja Pro:

      Place.Field.ACCESSIBILITY_OPTIONS*
          Użyj zamiast Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (wycofane).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Użyj zamiast Place.Field.ADDRESS (wycofane).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Użyj zamiast Place.Field.ICON_URL (wycofane).
      Place.Field.LOCATION*
          Użyj zamiast Place.Field.LAT_LNG (wycofane).
      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

      Pełną listę pól i powiązanych z nimi jednostek SKU znajdziesz w artykule Pola danych miejsca (nowe).

    • Te pola powodują wywołanie jednostki SKU Wyszukiwanie tekstowe – wersja Enterprise:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Użyj zamiast Place.Field.PHONE_NUMBER, które jest wycofane.
      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*
          * Użyj zamiast Place.Field.USER_RATINGS_TOTAL, które jest wycofane.
      Place.Field.WEBSITE_URI

      Pełną listę pól i powiązanych z nimi jednostek SKU znajdziesz w artykule Pola danych miejsca (nowe).

    • Te pola powodują wywołanie jednostki SKU Wyszukiwanie tekstowe – wersja Enterprise Plus:

      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

      Pełną listę pól i powiązanych z nimi jednostek SKU znajdziesz w artykule Pola danych miejsca (nowe).

    Aby ustawić parametr listy pól, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setPlaceFields().

  • Zapytanie tekstowe

    Ciąg tekstowy, na podstawie którego ma się odbywać wyszukiwanie, np. „restauracja”, „ul. Nowa 123” lub „najlepsze miejsce do odwiedzenia w Krakowie”. Interfejs API zwraca pasujące wyniki na podstawie tego ciągu znaków i porządkuje je według przewidywanej trafności.

    Aby ustawić parametr zapytania tekstowego, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setTextQuery().

Parametry opcjonalne

Aby określić parametry opcjonalne żądania, użyj obiektu SearchByTextRequest.

  • Uwzględniony typ

    Ogranicza wyniki do miejsc pasujących do określonego typu zdefiniowanego przez tabelę A. Można określić tylko 1 typ. Na przykład:

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

    Aby ustawić parametr uwzględnionego typu, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setIncludedType().

  • Preferencje lokalizacji

    Określa obszar wyszukiwania. Ta lokalizacja służy jako preferencja, co oznacza, że mogą być zwracane wyniki z okolic określonej lokalizacji, w tym wyniki spoza określonego obszaru.

    Możesz określić ograniczenie lokalizacji lub preferencje lokalizacji, ale nie oba te parametry naraz. Ograniczenie lokalizacji określa region, w którym muszą się znajdować wyniki, a preferencje lokalizacji określają region, w którym prawdopodobnie będą się znajdować wyniki lub w jego pobliżu. Pamiętaj, że w przypadku preferencji lokalizacji wyniki mogą nadal znajdować się poza określonym obszarem.

    Określ region jako prostokątny widoczny obszar lub okrąg.

    • Okrąg jest definiowany przez punkt środkowy i promień w metrach. Promień musi się mieścić w zakresie od 0,0 do 50000,0 włącznie. Na przykład:

      // 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();

    • Prostokąt to widoczny obszar szerokości i długości geograficznej, reprezentowany przez 2 punkty: dolny i górny, które znajdują się po przekątnej. Punkt dolny oznacza południowo-zachodni róg prostokąta, a punkt górny – północno-wschodni róg prostokąta.

      Widoczny obszar jest uważany za zamknięty region, co oznacza, że obejmuje swoje granice. Granice szerokości geograficznej muszą się mieścić w zakresie od -90 do 90 stopni włącznie, a granice długości geograficznej muszą się mieścić w zakresie od -180 do 180 stopni włącznie:

      • Jeśli low = high, widoczny obszar składa się z tego jednego punktu.
      • Jeśli low.longitude > high.longitude, zakres długości geograficznej jest odwrócony (widoczny obszar przecina linię długości geograficznej 180 stopni).
      • Jeśli low.longitude = -180 stopni i high.longitude = 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.
      • Jeśli low.longitude = 180 stopni i high.longitude = -180 stopni, zakres długości geograficznej jest pusty.
      • Jeśli low.latitude > high.latitude, zakres szerokości geograficznej jest pusty.

      Zarówno punkt dolny, jak i górny muszą być wypełnione, a reprezentowany przez nie prostokąt nie może być pusty. Pusty widoczny obszar powoduje błąd.

      Przykład prostokątnego widocznego obszaru znajdziesz w sekcji Żądania wyszukiwania tekstowego.

      Aby ustawić parametr preferencji lokalizacji, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setLocationBias().

  • Ograniczenie lokalizacji

    Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. Określ region jako prostokątny widoczny obszar. Informacje o definiowaniu widocznego obszaru znajdziesz w opisie preferencji lokalizacji.

    Możesz określić ograniczenie lokalizacji lub preferencje lokalizacji, ale nie oba te parametry naraz. Ograniczenie lokalizacji określa region, w którym muszą się znajdować wyniki, a preferencje lokalizacji określają region, w którym wyniki muszą się znajdować w pobliżu, ale mogą być poza obszarem.

    Aby ustawić parametr ograniczenia lokalizacji, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setLocationRestriction().

  • Maksymalna liczba wyników

    Określa maksymalną liczbę wyników miejsca do zwrócenia. Wartość musi się mieścić w zakresie od 1 do 20 (domyślnie) włącznie.

    Aby ustawić parametr maksymalnej liczby wyników, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setMaxResultCount().

  • Minimalna ocena

    Ogranicza wyniki tylko do tych, których średnia ocena użytkowników jest większa lub równa temu limitowi. Wartości muszą się mieścić w zakresie od 0,0 do 5,0 (włącznie) w odstępach co 0,5. Na przykład: 0, 0,5, 1,0, ..., 5,0 włącznie. Wartości są zaokrąglane w górę do najbliższej wartości 0,5. Na przykład wartość 0,6 eliminuje wszystkie wyniki z oceną niższą niż 1,0.

    Aby ustawić parametr minimalnej oceny, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setMinRating().

  • Teraz otwarte

    Jeśli wartość to true, zwracaj tylko te miejsca, które są otwarte w momencie wysłania zapytania. Jeśli wartość to false, zwracaj wszystkie firmy niezależnie od ich statusu otwarcia. Jeśli ustawisz ten parametr na false, zwracane będą miejsca, które nie mają określonych godzin otwarcia w bazie danych Miejsc Google.

    Aby ustawić parametr „Teraz otwarte”, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setOpenNow().

  • Poziomy cenowe

    Domyślnie wyniki obejmują miejsca, które świadczą usługi na wszystkich poziomach cenowych. Aby ograniczyć wyniki tylko do miejsc na określonych poziomach cenowych, możesz przekazać listę wartości całkowitych odpowiadających poziomom cenowym miejsc, które chcesz zwrócić:

    • 1 – miejsce oferuje niedrogie usługi.
    • 2 – miejsce oferuje usługi w umiarkowanych cenach.
    • 3 – miejsce oferuje drogie usługi.
    • 4 – miejsce oferuje bardzo drogie usługi.

    Aby ustawić parametr poziomów cenowych, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setPriceLevels().

  • Preferencje rankingu

    Określa, jak wyniki są klasyfikowane w odpowiedzi na podstawie typu zapytania:

    • W przypadku zapytania kategorycznego, takiego jak "Restauracje w Krakowie", SearchByTextRequest.RankPreference.RELEVANCE (klasyfikuj wyniki według trafności wyszukiwania) jest wartością domyślną. Możesz ustawić preferencje rankingu na SearchByTextRequest.RankPreference.RELEVANCE lub SearchByTextRequest.RankPreference.DISTANCE (klasyfikuj wyniki według odległości).
    • W przypadku zapytania niekategorycznego, takiego jak "Kraków", zalecamy pozostawienie parametru preferencji rankingu bez ustawienia.

    Aby ustawić parametr preferencji rankingu, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setRankPreference().

  • Kod regionu

    Kod regionu używany do formatowania odpowiedzi, określony jako 2-znakowa wartość kodu CLDR. Ten parametr może też wpływać na wyniki wyszukiwania. Nie ma wartości domyślnej.

    Jeśli nazwa kraju w polu adresu w odpowiedzi jest zgodna z kodem regionu, kod kraju jest pomijany w adresie.

    Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład kodem ccTLD Wielkiej Brytanii jest „uk” (.co.uk), a kodem ISO 3166-1 jest „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). Parametr może wpływać na wyniki na podstawie obowiązującego prawa.

    Aby ustawić parametr kodu regionu, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setRegionCode().

  • Ścisłe filtrowanie typu

    Używany z parametrem uwzględnionego typu. Gdy wartość jest ustawiona na true, zwracane są tylko miejsca pasujące do typów określonych przez parametr uwzględnionego typu. Gdy wartość to false (domyślnie), odpowiedź może zawierać miejsca, które nie pasują do określonych typów.

    Aby ustawić parametr ścisłego filtrowania typu, podczas tworzenia obiektu SearchByTextRequest wywołaj metodę setStrictTypeFiltering().