Wyszukiwanie w pobliżu (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa
Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Żądanie wyszukiwania w pobliżu (nowe) przyjmuje jako dane wejściowe region do wyszukania określony jako okrąg zdefiniowany przez współrzędne geograficzne środka okręgu i 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ź, podając listę typów miejsc, które mają być wyraźnie uwzględnione w odpowiedzi lub z niej wykluczone. Możesz na przykład określić, że w odpowiedzi mają się znaleźć tylko miejsca typu „restauracja”, „piekarnia” i „kawiarnia”, lub wykluczyć wszystkie miejsca typu „szkoła”.

Żądania wyszukiwania w pobliżu (nowe)

Wyślij żądanie wyszukiwania w pobliżu, wywołując metodę GMSPlacesClient searchNearbyWithRequest: i przekazując obiekt GMSPlaceSearchNearbyRequest, który definiuje parametry żądania, oraz metodę wywołania zwrotnego typu GMSPlaceSearchNearbyResultCallback do obsługi odpowiedzi.

Obiekt GMSPlaceSearchNearbyRequest 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ą w GMSPlaceProperty. Jeśli nie określisz co najmniej jednego pola na liście pól lub pominiesz listę pól, wywołanie zwróci błąd.
  • ograniczenie lokalizacji, czyli okrąg określający obszar wyszukiwania;

Ten przykład żądania wyszukiwania w pobliżu określa, że obiekty GMSPlace w odpowiedzi zawierają 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 w 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 z Wyszukiwania w pobliżu

Interfejs Nearby Search API zwraca tablicę wyników w postaci obiektów GMSPlace, przy czym każdy 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 jeden argument typu GMSPlaceIsOpenWithRequest, który zawiera:

  • GMSPlaceObiekt lub ciąg znaków określający identyfikator miejsca. Więcej informacji o tworzeniu obiektu Place z wymaganymi polami znajdziesz w sekcji Szczegóły miejsca.
  • Opcjonalny obiekt NSDate (Obj-C) lub Date (Swift) określający czas, który chcesz sprawdzić. Jeśli nie podasz czasu, zostanie użyta wartość domyślna „teraz”.
  • Metoda GMSPlaceOpenStatusResponseCallback do obsługi odpowiedzi.
    • >

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 funkcji 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 lub czy jej stan jest nieznany.

Język Wartość, jeśli jest otwarty Wartość, jeśli firma 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 konto isOpenWithRequest

Przykład: wysyłanie prośby GMSPlaceIsOpenWithRequest

Poniższy przykład pokazuje, jak zainicjować GMSPlaceIsOpenWithRequest w ramach istniejącego obiektu GMSPlace.

Pakiet SDK Miejsc w 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

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

  • Lista pól

    Gdy wysyłasz prośbę o szczegóły miejsca, musisz określić dane, które mają być zwracane w obiekcie GMSPlace dla miejsca jako maska 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 z kolei pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

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

    • Te pola wywołują kod SKU Nearby Search Pro:

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

    • Te pola wywołują kod SKU Nearby Search Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Następujące pola wywołują SKU Nearby Search Enterprise Plus:

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

    W tym przykładzie przekazywana jest lista 2 wartości pól, aby określić, że obiekt GMSPlace zwracany przez żądanie zawiera pola name i placeID:

    Pakiet SDK Miejsc w 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 wyszukiwania w postaci koła zdefiniowanego 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. W żądaniu musisz ustawić wartość większą niż 0,0.

Parametry opcjonalne

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Umożliwia określenie listy typów z tabeli A, które będą używane do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń dotyczących typu możesz określić maksymalnie 50 typów.

    Miejsce może mieć tylko jeden typ podstawowy z typów wymienionych w tabeli A. Na przykład typ podstawowy może być "mexican_restaurant" lub "steak_house". Użyj includedPrimaryTypes i excludedPrimaryTypes, aby filtrować wyniki według głównego typu miejsca.

    Miejsce może też mieć wiele wartości typu z typów Tabela A z nim powiązanych. Na przykład restauracja może mieć te typy: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Użyj znaków includedTypes i excludedTypes, aby filtrować wyniki na liście typów powiązanych z miejscem.

    Jeśli określisz ogólny typ podstawowy, np. "restaurant" lub "hotel", odpowiedź może zawierać miejsca o bardziej szczegółowym typie podstawowym niż podany. Na przykład określasz, że chcesz uwzględnić typ podstawowy "restaurant". Odpowiedź może wtedy zawierać miejsca z podstawowym typem "restaurant", ale może też zawierać miejsca z bardziej szczegółowym typem podstawowym, np. "chinese_restaurant" lub "seafood_restaurant".

    Jeśli wyszukiwanie jest ograniczone do kilku typów, 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órych chcesz wyszukać. 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 parametr 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ź zawiera miejsca, które pasują do co najmniej jednego z includedTypes i żadnego z excludedTypes.

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

    includedPrimaryTypes

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

    excludedPrimaryTypes

    Lista głównych typów miejsc z tabeli A, które mają zostać wykluczone z wyszukiwania.

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

  • maxResultCount

    Określa maksymalną liczbę wyników dotyczących miejsc do zwrócenia. Musi mieścić się w przedziale od 1 do 20 (wartość domyślna) włącznie.

  • rankPreference

    Typ rankingu do użycia. Jeśli ten parametr zostanie pominięty, wyniki będą 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, podany jako dwuznakowy kod CLDR. Nie ma wartości domyślnej.

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

    Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). W zależności od obowiązujących przepisów parametr może wpływać na wyniki.

Wyświetlanie atrybucji w aplikacji

Gdy aplikacja wyświetla informacje uzyskane z GMSPlacesClient, np. zdjęcia i opinie, musi też wyświetlać wymagane atrybucje.

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

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