Wyszukiwanie w pobliżu (nowość)

Wybierz platformę: Android iOS JavaScript Web Service
Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Żądanie wyszukiwania w pobliżu (nowego) przyjmuje jako dane wejściowe region, w którym ma się odbyć wyszukiwanie. Jest on określony jako okrąg zdefiniowany przez współrzędne geograficzne środka okręgu oraz promień w metrach. Żądanie zwraca listę pasujących miejsc, z których każde jest reprezentowane przez obiekt GMSPlace, w określonym obszarze wyszukiwania.

Domyślnie odpowiedź zawiera miejsca wszystkich typów w obszarze wyszukiwania. Opcjonalnie możesz filtrować odpowiedź, określając listę typów miejsc, które mają być wyraźnie uwzględnione lub wykluczone z odpowiedzi. Możesz na przykład określić, że w odpowiedzi mają się znajdować tylko miejsca typu „restauracja”, „piekarnia” i „kawiarnia”, lub wykluczyć wszystkie miejsca typu „szkoła”.

Żądania wyszukiwania w pobliżu (nowego)

Aby wysłać żądanie wyszukiwania w pobliżu, wywołaj metodę GMSPlacesClient searchNearbyWithRequest:, przekazując obiekt GMSPlaceSearchNearbyRequest , który określa parametry żądania, oraz metodę wywołania zwrotnego typu GMSPlaceSearchNearbyResultCallback, która będzie obsługiwać odpowiedź.

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

Ten przykład żądania wyszukiwania w pobliżu określa, że obiekty GMSPlace w odpowiedzi mają zawierać nazwę miejsca (GMSPlacePropertyName) i współrzędne miejsca (GMSPlacePropertyCoordinate) dla każdego obiektu GMSPlace w wynikach wyszukiwania. Filtruje też odpowiedź, aby zwracać tylko miejsca typu „restauracja” i „kawiarnia”.

Pakiet SDK Miejsc na Swift

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [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().searchNearby(with: request, callback: callback)

Objective-C

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

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

Odpowiedzi wyszukiwania w pobliżu

Interfejs Nearby Search API zwraca tablicę dopasowań w postaci GMSPlace obiektów, przy czym każdy pasujący obiekt GMSPlace 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 tych pól w obiekcie GMSPlace:

  • 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 miejsce jest otwarte Wartość, jeśli miejsce jest 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 isOpenWithRequest

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

Przykład: wysyłanie żądania GMSPlaceIsOpenWithRequest

Ten 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
            }
          }];

Wymagane parametry

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

  • Lista pól

    Gdy prosisz o szczegóły miejsca, musisz określić dane, które mają być zwracane w obiekcie GMSPlace dla tego miejsca, jako maskę pola. Aby zdefiniować maskę pola, przekaż tablicę wartości z GMSPlaceProperty do obiektu GMSPlaceSearchNearbyRequest. Maskowanie 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:

    • Te pola aktywują jednostkę SKU Wyszukiwanie w pobliżu – wersja Pro:

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

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

    • Te pola aktywują jednostkę SKU Wyszukiwanie w pobliżu – wersja Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

    • Te pola aktywują jednostkę SKU Wyszukiwanie w pobliżu – wersja 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 jednostek SKU znajdziesz w artykule Pola danych o miejscach (nowe).

    Ten przykład przekazuje listę 2 wartości pól aby określić, że obiekt GMSPlace zwracany przez żądanie ma zawierać pola name i placeID:

    Pakiet SDK Miejsc na Swift

    // Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

    Swift

    // Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

    Objective-C

    // Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

  • locationRestriction

    Obiekt GMSPlaceLocationRestriction określający region, w którym ma się odbyć wyszukiwanie. Jest on zdefiniowany jako okrąg zdefiniowany przez środek 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. W żądaniu musisz ustawić wartość większą niż 0,0.

Parametry opcjonalne

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Pozwala określić listę typów z tabeli A, które mają być używane do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu można określić maksymalnie 50 typów.

    Miejsce może mieć powiązany tylko 1 typ podstawowy z tabeli A. Typ podstawowy może być np. "mexican_restaurant" lub "steak_house". Użyj includedPrimaryTypes i excludedPrimaryTypes, aby filtrować wyniki według typu podstawowego miejsca.

    Miejsce może też mieć powiązanych wiele wartości typu z typów tabeli A. Restauracja może mieć na przykład te typy: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Użyj includedTypes i excludedTypes, aby filtrować wyniki według listy typów powiązanych z miejscem.

    Jeśli określisz ogólny typ podstawowy, np. "restaurant" lub "hotel", odpowiedź może zawierać miejsca z bardziej szczegółowym typem podstawowym niż ten, który został określony. Na przykład określisz, że ma być uwzględniony typ podstawowy "restaurant". Odpowiedź może wtedy zawierać miejsca z typem podstawowym "restaurant", ale może też zawierać miejsca z bardziej szczegółowym typem podstawowym, np. "chinese_restaurant" lub "seafood_restaurant".

    Jeśli wyszukiwanie jest określone z kilkoma ograniczeniami typu, zwracane są tylko miejsca które spełniają wszystkie ograniczenia. Jeśli na przykład określisz {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, zwrócone miejsca będą świadczyć usługi związane z "restaurant", ale nie będą działać głównie jako "steak_house".

    includedTypes

    Lista typów miejsc z tabeli A, które mają być wyszukiwane. Jeśli ten parametr zostanie pominięty, zwracane są miejsca wszystkich typów.

    excludedTypes

    Lista typów miejsc z tabeli A, które mają być wykluczone z wyszukiwania.

    Jeśli w żądaniu określisz zarówno includedTypes (np. "school"), jak i excludedTypes (np. "primary_school"), odpowiedź będzie zawierać miejsca, które są sklasyfikowane jako "school" ale nie jako "primary_school". Odpowiedź będzie zawierać miejsca, które pasują do co najmniej 1 z includedTypes i żadnego z excludedTypes.

    Jeśli występują sprzeczne typy, np. typ pojawia się zarówno w includedTypes i excludedTypes, zwracany jest błąd INVALID_REQUEST.

    includedPrimaryTypes

    Lista podstawowych typów miejsc z tabeli A, które mają być uwzględnione w wyszukiwaniu.

    excludedPrimaryTypes

    Lista podstawowych typów miejsc z tabeli A, które mają być wykluczone z wyszukiwania.

    Jeśli występują sprzeczne typy podstawowe, np. typ pojawia się zarówno w includedPrimaryTypes i excludedPrimaryTypes, zwracany jest błąd INVALID_ARGUMENT.

  • maxResultCount

    Określa maksymalną liczbę wyników wyszukiwania miejsc, które mają być zwracane. Musi mieścić się w zakresie od 1 do 20 (domyślnie) włącznie.

  • rankPreference

    Typ rankingu, którego należy użyć. Jeśli ten parametr zostanie pominięty, wyniki są sortowane według popularności. Może mieć jedną z tych wartości:

    • .popularity (domyślnie) – sortuje wyniki według popularności.
    • .distance – sortuje wyniki w kolejności rosnącej według odległości od określonej lokalizacji.

  • regionCode

    Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowa wartość kodu CLDR. Nie ma wartości domyślnej.

    Jeśli nazwa kraju w polu formattedAddress w odpowiedzi pasuje do regionCode, kod kraju jest pomijany w formattedAddress. Ten parametr nie ma wpływu na adrFormatAddress, które zawsze zawiera nazwę kraju, ani na shortFormattedAddress, które nigdy jej nie zawiera.

    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”). Parametr może wpływać na wyniki na podstawie obowiązującego prawa.

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 na temat atrybucji.