Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst
Entwickler im Europäischen Wirtschaftsraum (EWR)

Für eine „Nearby Search (New)“-Anfrage wird die Region, in der gesucht werden soll, als Kreis angegeben, der durch die Breiten- und Längengradkoordinaten des Mittelpunkts des Kreises und den Radius in Metern definiert wird. Die Anfrage gibt eine Liste übereinstimmender Orte zurück, die jeweils durch ein GMSPlace-Objekt im angegebenen Suchbereich dargestellt werden.

Standardmäßig enthält die Antwort Orte aller Typen im Suchbereich. Optional können Sie die Antwort filtern, indem Sie eine Liste von Ortstypen angeben, die explizit in die Antwort aufgenommen oder aus der Antwort ausgeschlossen werden sollen. Sie können beispielsweise festlegen, dass in der Antwort nur Orte vom Typ „Restaurant“, „Bäckerei“ und „Café“ enthalten sein sollen, oder alle Orte vom Typ „Schule“ ausschließen.

„Nearby Search (New)“-Anfragen

Stellen Sie eine Anfrage vom Typ „Nearby Search“, indem Sie GMSPlacesClient searchNearbyWithRequest: aufrufen und ein GMSPlaceSearchNearbyRequest-Objekt übergeben, das die Anfrageparameter definiert, sowie eine Callback-Methode vom Typ GMSPlaceSearchNearbyResultCallback, um die Antwort zu verarbeiten.

Das GMSPlaceSearchNearbyRequest-Objekt gibt alle erforderlichen und optionalen Parameter für die Anfrage an. Zu den erforderlichen Parametern gehören:

  • Die Liste der Felder, die im GMSPlace-Objekt zurückgegeben werden sollen, auch Feldmaske genannt, wie durch GMSPlaceProperty definiert. Wenn Sie in der Feldliste nicht mindestens ein Feld angeben oder die Feldliste weglassen, gibt der Aufruf einen Fehler zurück.
  • Die Standortbeschränkung, also der Kreis, der den Suchbereich definiert.

In diesem Beispiel für eine Nearby Search-Anfrage wird angegeben, dass die Antwortobjekte GMSPlace den Ortsnamen (GMSPlacePropertyName) und die Ortskoordinaten (GMSPlacePropertyCoordinate) für jedes GMSPlace-Objekt in den Suchergebnissen enthalten. Außerdem wird die Antwort so gefiltert, dass nur Orte vom Typ „Restaurant“ und „Café“ zurückgegeben werden.

Places Swift SDK

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

„Nearby Search“-Antworten

Die Nearby Search API gibt ein Array von Übereinstimmungen in Form von GMSPlace-Objekten zurück, wobei es ein GMSPlace-Objekt pro übereinstimmendem Ort gibt.

Öffnungsstatus abrufen

Das Objekt GMSPlacesClient enthält eine Member-Funktion namens isOpenWithRequest (isOpenRequest in Swift und isPlaceOpenRequest in GooglePlacesSwift), die eine Antwort zurückgibt, die angibt, ob der Ort derzeit geöffnet ist, basierend auf der im Aufruf angegebenen Zeit.

Diese Methode verwendet ein einzelnes Argument vom Typ GMSPlaceIsOpenWithRequest, das Folgendes enthält:

  • Ein GMSPlace-Objekt oder ein String, der eine Orts-ID angibt. Weitere Informationen zum Erstellen des Place-Objekts mit den erforderlichen Feldern finden Sie unter Ortsdetails.
  • Ein optionales NSDate- (Obj-C) oder Date-Objekt (Swift), das die Uhrzeit angibt, die Sie prüfen möchten. Wenn keine Zeit angegeben ist, wird standardmäßig die aktuelle Zeit verwendet.
  • Eine GMSPlaceOpenStatusResponseCallback-Methode zur Verarbeitung der Antwort.
    • >

Für die Methode GMSPlaceIsOpenWithRequest müssen die folgenden Felder im Objekt GMSPlace festgelegt werden:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Wenn diese Felder nicht im Place-Objekt angegeben sind oder Sie eine Orts-ID übergeben, werden sie mit GMSPlacesClient GMSFetchPlaceRequest: abgerufen.

isOpenWithRequest Antwort

isOpenWithRequest gibt ein GMSPlaceIsOpenResponse-Objekt mit einem booleschen Wert namens status zurück, der angibt, ob das Unternehmen geöffnet oder geschlossen ist oder ob der Status unbekannt ist.

Sprache Wert bei geöffnetem Zustand Wert, wenn geschlossen Wert, wenn der Status unbekannt ist
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Abrechnung für „isOpenWithRequest“

  • Die Felder GMSPlacePropertyUTCOffsetMinutes und GMSPlacePropertyBusinessStatus werden unter der Basic Data-SKU in Rechnung gestellt. Die restlichen Öffnungszeiten werden unter der Place Details Enterprise-SKU abgerechnet.
  • Wenn Ihr GMSPlace-Objekt diese Felder bereits aus einer früheren Anfrage enthält, werden Ihnen keine weiteren Kosten in Rechnung gestellt.

Beispiel: GMSPlaceIsOpenWithRequest-Anfrage stellen

Im folgenden Beispiel sehen Sie, wie Sie ein GMSPlaceIsOpenWithRequest-Objekt in einem vorhandenen GMSPlace-Objekt initialisieren.

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

Erforderliche Parameter

Verwenden Sie das GMSPlaceSearchNearbyRequest-Objekt, um die erforderlichen Parameter für die Suche anzugeben.

  • Feldliste

    Wenn Sie Ortsdetails anfordern, müssen Sie die Daten, die im GMSPlace-Objekt für den Ort zurückgegeben werden sollen, als Feldmaske angeben. Um die Feldmaske zu definieren, übergeben Sie ein Array von Werten aus GMSPlaceProperty an das GMSPlaceSearchNearbyRequest-Objekt. Mit der Maskierung von Feldern lässt sich verhindern, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.

    Geben Sie eines oder mehrere der folgenden Felder an:

    • Die folgenden Felder lösen die Nearby Search Pro-SKU aus:

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

    • Die folgenden Felder lösen die Nearby Search Enterprise-SKU aus:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Die folgenden Felder lösen die Nearby Search Enterprise Plus-SKU aus:

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

    Im folgenden Beispiel wird eine Liste mit zwei Feldwerten übergeben, um anzugeben, dass das von einer Anfrage zurückgegebene GMSPlace-Objekt die Felder name und placeID enthält:

    Places Swift SDK

    // 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

    Ein GMSPlaceLocationRestriction-Objekt, das den zu durchsuchenden Bereich als Kreis mit Mittelpunkt und Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 liegen (jeweils einschließlich). Der Standardradius ist 0,0. Sie müssen in Ihrer Anfrage einen Wert größer als 0,0 festlegen.

Optionale Parameter

Mit dem GMSPlaceSearchNearbyRequest-Objekt können Sie die optionalen Parameter für die Suche angeben.

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Hiermit können Sie eine Liste von Typen aus Tabelle A angeben, die zum Filtern der Suchergebnisse verwendet werden. In jeder Kategorie für Typbeschränkungen können bis zu 50 Typen angegeben werden.

    Ein Ort kann nur einen primären Typ aus den Typen in Tabelle A haben. Der primäre Typ kann beispielsweise "mexican_restaurant" oder "steak_house" sein. Verwenden Sie includedPrimaryTypes und excludedPrimaryTypes, um die Ergebnisse nach dem primären Typ eines Orts zu filtern.

    Ein Ort kann auch mehrere Typwerte aus Typen in Tabelle A haben. Ein Restaurant kann beispielsweise die folgenden Typen haben: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Mit includedTypes und excludedTypes können Sie die Ergebnisse nach der Liste der Typen filtern, die einem Ort zugeordnet sind.

    Wenn Sie einen allgemeinen primären Typ wie "restaurant" oder "hotel" angeben, kann die Antwort Orte mit einem spezifischeren primären Typ als dem angegebenen enthalten. Sie geben beispielsweise an, dass der primäre Typ "restaurant" eingeschlossen werden soll. Die Antwort kann dann Orte mit dem primären Typ "restaurant" enthalten, aber auch Orte mit einem spezifischeren primären Typ wie "chinese_restaurant" oder "seafood_restaurant".

    Wenn für eine Suche mehrere Typeinschränkungen angegeben sind, werden nur Orte zurückgegeben, die alle Einschränkungen erfüllen. Wenn Sie beispielsweise {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} angeben, bieten die zurückgegebenen Orte "restaurant"-bezogene Dienste an, sind aber nicht in erster Linie als "steak_house" tätig.

    includedTypes

    Eine Liste der Ortstypen aus Tabelle A, nach denen gesucht werden soll. Wenn dieser Parameter weggelassen wird, werden Orte aller Typen zurückgegeben.

    excludedTypes

    Eine Liste der Ortstypen aus Tabelle A, die aus einer Suche ausgeschlossen werden sollen.

    Wenn Sie sowohl includedTypes (z. B. "school") als auch excludedTypes (z. B. "primary_school") in der Anfrage angeben, enthält die Antwort Orte, die als "school", aber nicht als "primary_school" kategorisiert sind. Die Antwort enthält Orte, die mindestens einer der includedTypes und keiner der excludedTypes entsprechen.

    Wenn es Konflikte zwischen Typen gibt, z. B. wenn ein Typ sowohl in includedTypes als auch in excludedTypes vorkommt, wird ein INVALID_REQUEST-Fehler zurückgegeben.

    includedPrimaryTypes

    Eine Liste der primären Ortstypen aus Tabelle A, die in eine Suche aufgenommen werden sollen.

    excludedPrimaryTypes

    Eine Liste der primären Ortstypen aus Tabelle A, die aus einer Suche ausgeschlossen werden sollen.

    Wenn es primäre Typen gibt, die in Konflikt stehen, z. B. ein Typ, der sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes vorkommt, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.

  • maxResultCount

    Gibt die maximale Anzahl der zurückzugebenden Ortsangabe-Ergebnisse an. Muss zwischen 1 und 20 (Standard) liegen.

  • rankPreference

    Der zu verwendende Rankingtyp. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Mögliche Werte:

    • .popularity (Standard): Die Ergebnisse werden nach Beliebtheit sortiert.
    • .distance: Sortiert die Ergebnisse in aufsteigender Reihenfolge nach ihrer Entfernung vom angegebenen Ort.

  • regionCode

    Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code. Es gibt keinen Standardwert.

    Wenn der Ländername des Felds formattedAddress in der Antwort mit regionCode übereinstimmt, wird der Ländercode aus formattedAddress entfernt. Dieser Parameter hat keine Auswirkungen auf adrFormatAddress, das immer den Ländernamen enthält, oder auf shortFormattedAddress, das ihn nie enthält.

    Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs ist beispielsweise „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für das Land „Vereinigtes Königreich von Großbritannien und Nordirland“). Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.

Zuordnungen in der App anzeigen

Wenn in Ihrer App Informationen angezeigt werden, die durch Aufrufen von GMSPlacesClient eingeholt wurden, z. B. Fotos und Rezensionen, müssen auch die erforderlichen Quellenangaben eingeblendet werden.

Das Attribut reviews des GMSPlacesClient-Objekts enthält beispielsweise ein Array mit bis zu fünf GMSPlaceReview-Objekten. Jedes GMSPlaceReview-Objekt kann Quellenangaben und Quellenangaben zum Autor enthalten. Wenn Sie die Rezension in Ihrer App anzeigen, müssen Sie auch alle Quellenangaben oder Autorenangaben anzeigen.

Weitere Informationen finden Sie in der Dokumentation zu Quellenangaben.