Wyszukaj tekst (nowa funkcja)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

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

Oprócz wymaganych parametrów funkcja wyszukiwania tekstowego (nowa) obsługuje doprecyzowywanie zapytań za pomocą parametrów opcjonalnych, co pozwala uzyskać lepsze wyniki.

Pobieranie listy miejsc za pomocą wyszukiwania tekstowego

Wyślij żądanie wyszukiwania tekstowego, wywołując funkcję GMSPlacesClient searchByTextWithRequest: i przekazując obiekt GMSPlaceSearchByTextRequest, który definiuje parametry żądania, oraz metodę wywołania zwrotnego typu GMSPlaceSearchByTextResultCallback do obsługi odpowiedzi.

Obiekt GMSPlaceSearchByTextRequest określa wszystkie wymagane i opcjonalne parametry żądania. Wymagane parametry:

  • Lista pól do zwrócenia w obiekcie GMSPlace, nazywana też maską pola, zgodnie z definicją GMSPlaceProperty. Jeśli nie określisz co najmniej jednego pola na liście pól lub jeśli pominiesz listę pól, wywołanie zwróci błąd.
  • Zapytanie tekstowe.

W tym przykładowym żądaniu wyszukiwania tekstowego określono, że obiekty GMSPlace odpowiedzi zawierają nazwę i identyfikator miejsca dla każdego obiektu GMSPlace w wynikach wyszukiwania. Filtruje też odpowiedź, aby zwracała tylko miejsca typu „restauracja”.

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

Odpowiedzi wyszukiwania tekstowego

Interfejs Text Search API zwraca tablicę dopasowań w postaci obiektów GMSPlace, przy czym dla każdego pasującego miejsca zwracany jest 1 obiekt GMSPlace.

Uzyskiwanie informacji o stanie otwarcia

Obiekt GMSPlacesClient zawiera funkcję składową o nazwie isOpenWithRequest (isOpenRequest w Swift i isPlaceOpenRequest w GooglePlacesSwift), która zwraca odpowiedź wskazującą, czy miejsce jest obecnie otwarte, na podstawie czasu określonego w wywołaniu funkcji.

Ta metoda przyjmuje jeden argument typu GMSPlaceIsOpenWithRequest, który zawiera:

  • Obiekt GMSPlace lub ciąg znaków określający identyfikator miejsca. Więcej informacji o tworzeniu obiektu Place z wymaganymi polami znajdziesz w artykule informacje o miejscu.
  • Opcjonalny obiekt NSDate (Obj-C) lub Date (Swift) określający czas, który chcesz sprawdzić. Jeśli nie podasz godziny, domyślnie zostanie użyta bieżąca godzina.
  • Metoda GMSPlaceOpenStatusResponseCallback do obsługi odpowiedzi.
    • >

Metoda GMSPlaceIsOpenWithRequest wymaga ustawienia tych pól w obiekcie GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Jeśli te pola nie są podane w obiekcie Place lub jeśli przekazujesz identyfikator miejsca, metoda używa GMSPlacesClient GMSFetchPlaceRequest:, aby je pobrać.

isOpenWithRequest odpowiedź

isOpenWithRequest zwraca obiekt GMSPlaceIsOpenResponse zawierający wartość logiczną o nazwie status, która wskazuje, czy firma jest otwarta, zamknięta czy jej stan jest nieznany.

Język Wartość, jeśli otwarte Wartość, jeśli zamknięte Wartość, jeśli stan jest nieznany
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Płatności za konto isOpenWithRequest

Przykład: wysyłanie żądania GMSPlaceIsOpenWithRequest

Poniższy przykład pokazuje, jak zainicjować obiekt GMSPlaceIsOpenWithRequest w istniejącym obiekcie GMSPlace.

Places Swift SDK

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

Podział na strony

Wyszukiwanie tekstowe udostępnia obiekt podziału na strony, czyli wartość logiczną hasNextPage, która jest zwracana w pierwszej odpowiedzi na wywołanie wyszukiwania tekstowego. Jeśli dostępna jest następna strona, możesz ją wczytać za pomocą funkcji fetchNextPage().

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

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

Wymagane parametry

Użyj obiektu GMSPlaceSearchByTextRequest, aby określić wymagane parametry wyszukiwania.

  • Lista pól

    Określ, które właściwości danych o miejscu mają być zwracane. Przekaż listę właściwości GMSPlace określających pola danych do zwrócenia. Jeśli pominiesz maskę pola, żądanie zwróci błąd.

    Listy pól to dobra praktyka projektowa, 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 aktywują SKU Wyszukaj tekst Essentials ID Only:

      GMSPlacePropertyPlaceID

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

    • Te pola aktywują SKU Wyszukaj tekst Pro:

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyName
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

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

    • Te pola aktywują SKU Wyszukaj tekst Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

    • Te pola aktywują SKU Wyszukaj tekst Enterprise Plus:

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

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

  • textQuery

    Ciąg tekstowy, który ma zostać wyszukany, np. „restauracja”, „ul. Główna 123” lub „najlepsze miejsce do odwiedzenia w San Francisco”.

Parametry opcjonalne

Użyj obiektu GMSPlaceSearchByTextRequest, aby określić opcjonalne parametry wyszukiwania.

  • includedType

    Ogranicza wyniki do miejsc pasujących do określonego typu zdefiniowanego w Tabeli A. Można określić tylko jeden typ. Na przykład:

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    Jeśli ma wartość true, zwracane są tylko te miejsca, które są otwarte w momencie wysłania zapytania. Jeśli false, zwróć wszystkie firmy niezależnie od stanu 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.

  • isStrictTypeFiltering

    Jest używany z parametrem includeType. Jeśli ustawisz wartość true, zwracane będą tylko miejsca pasujące do określonych typów określonych przez includeType. Jeśli ma wartość false (domyślnie), odpowiedź może zawierać miejsca, które nie pasują do określonych typów.

  • locationBias

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

    Możesz określić locationRestriction lub locationBias, ale nie obie te wartości. Parametr locationRestriction określa region, w którym muszą znajdować się wyniki, a parametr locationBias określa region, w pobliżu którego muszą znajdować się wyniki, ale mogą być poza tym 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 mieścić się w zakresie od 0,0 do 50 000,0 włącznie. Domyślny promień to 0,0. Na przykład:

      let request = SearchByTextRequest()
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

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

      Widoczny obszar jest uważany za region zamknięty, co oznacza, że obejmuje on swoje granice. Szerokość geograficzna musi mieścić się w zakresie od -90 do 90 stopni, a długość geograficzna – od -180 do 180 stopni:

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

  • locationRestriction

    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 locationBias.

    Możesz określić locationRestriction lub locationBias, ale nie obie te wartości. Parametr locationRestriction określa region, w którym muszą znajdować się wyniki, a parametr locationBias określa region, w pobliżu którego muszą znajdować się wyniki, ale mogą być poza tym obszarem.

  • maxResultCount

    Określa maksymalną liczbę wyników dotyczących miejsc, które mają zostać zwrócone. Musi należeć do zakresu od 1 do 20 (domyślnie) włącznie.

  • minRating

    Ogranicza wyniki tylko do tych, których średnia ocena użytkowników jest większa lub równa temu limitowi. Wartości muszą mieścić się w zakresie od 0,0 do 5,0 (włącznie) i być wielokrotnością 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 wielokrotności 0,5. Na przykład wartość 0,6 eliminuje wszystkie wyniki z oceną mniejszą niż 1,0.

  • priceLevels

    Ogranicz wyszukiwanie do miejsc oznaczonych określonymi poziomami cen. Domyślnie wybrane są wszystkie poziomy cen.

    Podaj tablicę zawierającą co najmniej 1 wartość zdefiniowaną przez PriceLevel.

    Na przykład:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

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

    • W przypadku zapytania kategorialnego, takiego jak „Restauracje w Nowym Jorku”, domyślną wartością jest .relevance (wyniki są sortowane według trafności wyszukiwania). Możesz ustawić parametr rankPreference na .relevance lub .distance (wyniki będą sortowane według odległości).
    • W przypadku zapytania, które nie jest kategorią, np. „Mountain View, CA”, zalecamy pozostawienie parametru rankPreference bez ustawionej wartości.

  • regionCode

    Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowy kod 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 wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). Parametr może wpływać na wyniki na podstawie obowiązujących przepisów.

  • shouldIncludePureServiceAreaBusinesses

    Jeśli true, zwraca w wynikach wyszukiwania firmy działające wyłącznie na określonym obszarze. Firma działająca wyłącznie na określonym obszarze to firma, która świadczy usługi na miejscu u klienta lub samodzielnie dostarcza produkty odbiorcom, ale nie obsługuje klientów pod swoim adresem.

    Na przykład:

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

Wyświetlanie atrybucji w aplikacji

Gdy aplikacja wyświetla informacje uzyskane z GMSPlacesClient, takie jak zdjęcia i opinie, musi też wyświetlać wymagane informacje o autorze.

Na przykład właściwość reviews obiektu GMSPlacesClient zawiera tablicę z maksymalnie 5 obiektami GMSPlaceReview. Każdy obiekt GMSPlaceReview może zawierać atrybucje i atrybucje autora. Jeśli wyświetlasz opinię w aplikacji, musisz też wyświetlić informacje o autorze.

Więcej informacji znajdziesz w dokumentacji dotyczącej atrybucji.