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 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ź, podając listę typów miejsc, które mają być 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 wyznaczający obszar wyszukiwania.

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 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 pasujący obiekt GMSPlace odpowiada jednemu 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 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ść w przypadku zamknięcia 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 GMSPlaceIsOpenWithRequest prośby

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 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 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 Wyszukiwania w pobliżu (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 jako okrąg zdefiniowany 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 są 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. Typ podstawowy może być np. "mexican_restaurant" lub "steak_house". Użyj właściwości 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 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 pojawiający 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, którego chcesz użyć. 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, określony 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, 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 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.

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