Wyszukaj tekst (nowa funkcja)

Wybierz platformę: Android iOS JavaScript Web Service

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

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

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

Pobieranie listy miejsc za pomocą wyszukiwania tekstu

Wyślij żądanie wyszukiwania tekstu, wywołując metodę GMSPlacesClient searchByTextWithRequest:, przekazując obiekt GMSPlaceSearchByTextRequest , który określa 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 to:

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

Ten przykładowy tekstowy żądanie wyszukiwania określa, że obiekty GMSPlace w odpowiedzi mają zawierać nazwę i identyfikator miejsca dla każdego obiektu GMSPlace w wynikach wyszukiwania. Filtruje też odpowiedź, aby zwracać tylko miejsca typu „restauracja”.

Pakiet SDK Miejsc na Swift

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 na wyszukiwanie tekstu

Interfejs Text Search API zwraca tablicę dopasowań w postaci GMSPlace obiektów, przy czym każdy GMSPlace obiekt odpowiada jednemu pasującemu miejscu.

Pobieranie stanu 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.

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Jeśli te pola nie są podane w obiekcie Place lub jeśli przekażesz identyfikator miejsca, metoda użyje GMSPlacesClient GMSFetchPlaceRequest: do ich pobrania.

Odpowiedź isOpenWithRequest

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

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

Płatności za isOpenWithRequest

  • Pola GMSPlacePropertyUTCOffsetMinutes i GMSPlacePropertyBusinessStatus są rozliczane w ramach jednostki SKU Dane podstawowe. Pozostałe godziny otwarcia są rozliczane w ramach jednostki SKU Informacje o miejscu Enterprise.
  • Jeśli obiekt GMSPlace już zawiera te pola z poprzedniego żądania, nie zostaną naliczone dodatkowe opłaty.

Przykład: wysyłanie żądania GMSPlaceIsOpenWithRequest

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

Pakiet SDK Miejsc na Swift

        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 tekstu udostępnia obiekt podziału na strony, czyli wartość logiczną hasNextPage, która jest zwracana w pierwszej odpowiedzi na wywołanie wyszukiwania tekstu. Jeśli dostępna jest następna strona, możesz ją wczytać za pomocą funkcji fetchNextPage() aby wczytać ją.

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

Aby określić wymagane parametry wyszukiwania, użyj obiektu GMSPlaceSearchByTextRequest.

  • Lista pól

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

    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 1 z tych pól:

    • Następujące pola wywołują jednostkę SKU Wyszukaj tekst podstawowe zasady dotyczące wyszukiwarki – tylko identyfikator:

      GMSPlacePropertyPlaceID

    • Te pola wywołują jednostkę SKU Wyszukiwanie tekstu Pro:

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

    • Te pola wywołują jednostkę SKU Wyszukiwanie tekstu Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Te pola wywołują jednostkę SKU Wyszukiwanie tekstu Enterprise Plus:

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

  • textQuery

    Ciąg znaków, na podstawie którego ma być przeprowadzane wyszukiwanie, np. „restauracja”, „ul. Główna 123 ” lub „najlepsze miejsce do odwiedzenia w San Francisco”.

Parametry opcjonalne

Aby określić opcjonalne parametry wyszukiwania, użyj obiektu GMSPlaceSearchByTextRequest.

  • includedType

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

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

  • isOpenNow

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

  • isStrictTypeFiltering

    Używany z parametrem includeType. Gdy wartość jest ustawiona na true, zwracane są tylko miejsca pasujące do typów określonych przez includeType. Gdy wartość jest ustawiona na `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 preferencja, co oznacza, że mogą być zwracane wyniki z okolic określonej lokalizacji, w tym wyniki spoza określonego obszaru.

    Możesz określić locationRestriction lub locationBias, ale nie oba te parametry. Parametr locationRestriction określa region, w którym muszą się znajdować wyniki, a parametr locationBias określa region, w pobliżu którego muszą się znajdować wyniki, ale mogą one 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 50000,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: dolny i górny. 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ą mieścić się w zakresie od -90 do 90 stopni włącznie, a granice długości geograficznej – 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, 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 parametru locationBias.

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

  • maxResultCount

    Określa maksymalną liczbę wyników miejsca do zwrócenia. Wartość musi mieścić się w zakresie 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) 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.

  • priceLevels

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

    Określ 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ą klasyfikowane w odpowiedzi na podstawie typu zapytania:

    • W przypadku zapytania kategorycznego, takiego jak "Restauracje w Nowym Jorku", .relevance (klasyfikuj wyniki według trafności wyszukiwania) jest domyślne. Możesz ustawić rankPreference na .relevance lub .distance (klasyfikuj wyniki według odległości).
    • W przypadku zapytania niekategorycznego, takiego jak "Mountain View, Kalifornia", zalecamy pozostawienie parametru rankPreference bez ustawienia.

  • regionCode

    Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowa 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 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”). Ten parametr może wpływać na wyniki na podstawie obowiązującego prawa.

  • shouldIncludePureServiceAreaBusinesses

    Jeśli wartość to true, w wynikach wyszukiwania zwracane są firmy działające na określonym obszarze. Firma działająca 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:

    Pakiet SDK Miejsc na Swift

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

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

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