Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Für diese Funktion müssen Sie die Places API (New) aktivieren, die nächste Generation der Places API. Weitere Informationen finden Sie unter APIs aktivieren.

Bei einer Nearby Search (New)-Anfrage wird als Eingabe die zu durchsuchende Region angegeben, die als Kreis definiert ist. Dieser Kreis wird durch die Breiten- und Längengradkoordinaten des Mittelpunkts und den Radius in Metern definiert. Die Anfrage gibt eine Liste der übereinstimmenden Orte zurück, die jeweils durch ein GMSPlace-Objekt im angegebenen Suchgebiet dargestellt werden.

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

Nearby Search (New)-Anfragen

Rufen Sie GMSPlacesClient searchNearbyWithRequest: auf, um eine Nearby Search-Anfrage zu stellen, und übergeben Sie ein GMSPlaceSearchNearbyRequest-Objekt, das die Anfrageparameter definiert, sowie eine Callback-Methode vom Typ GMSPlaceSearchNearbyResultCallback, um die Antwort zu verarbeiten.

Im GMSPlaceSearchNearbyRequest-Objekt werden alle erforderlichen und optionalen Parameter für die Anfrage angegeben. Zu den erforderlichen Parametern gehören:

• Die Liste der Felder, die im GMSPlace-Objekt zurückgegeben werden sollen, auch Feldmaske genannt, wie von 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 das Suchgebiet definiert.

In dieser Beispielanfrage für die Nearby Search wird angegeben, dass die Antwort-GMSPlace-Objekte den Ortsnamen (GMSPlacePropertyName) und die Ortskoordinaten (GMSPlacePropertyCoordinate) für jedes GMSPlace-Objekt in den Suchergebnissen enthalten sollen. Außerdem werden nur Orte vom Typ „Restaurant“ und „Café“ zurückgegeben.

SwiftObjective-CPlaces Swift SDK for iOS (Vorabversion)

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

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

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
}

Nearby Search-Antworten

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

Hinweis : Die Felder des Antwortobjekts GMSPlace dürfen nicht leer sein. Wenn die Feldliste beispielsweise GMSPlacePropertyPhotos enthält, um das Feld photos in der Antwort anzufordern, und das Feld photos in der Antwort leer ist, wird es aus dem Antwortobjekt GMSPlace entfernt.

Status „Offen“ abrufen

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

Hinweis:Die eingestellten Funktionen GMSPlace isOpen: und GMSPlace isOpenAtDate: sind möglicherweise ungenau und nicht für die Verwendung mit der Places API (neu) vorgesehen.

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

• Ein GMSPlace-Objekt oder ein String, der eine Orts-ID angibt. Weitere Informationen zum Erstellen des Ortsobjekts mit den erforderlichen Feldern finden Sie unter Place Details.
  
  Hinweis:Das Ortsobjekt muss eine gültige Orts-ID enthalten.
• Ein optionales NSDate-Objekt (Obj-C) oder Date-Objekt (Swift), das die Zeit angibt, die geprüft werden soll. Wenn keine Zeit angegeben ist, wird standardmäßig die aktuelle Zeit verwendet.
• Eine GMSPlaceOpenStatusResponseCallback-Methode zum Verarbeiten der Antwort.
>

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

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

Wenn diese Felder nicht im Ortsobjekt angegeben sind oder Sie eine Orts-ID übergeben, werden sie mithilfe von 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öffnet	Wert bei geschlossenem Status	Wert, wenn Status unbekannt
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown
GooglePlacesSwift (Vorabversion)	true	false	nil

Abrechnung für „isOpenWithRequest“

• Die Felder GMSPlacePropertyUTCOffsetMinutes und GMSPlacePropertyBusinessStatus werden unter der SKU „Basic Data“ in Rechnung gestellt. Die restlichen Öffnungszeiten werden über die Place Details Enterprise-SKU abgerechnet.
• Wenn Ihr GMSPlace-Objekt bereits diese Felder aus einer früheren Anfrage enthält, werden Ihnen keine zusätzlichen Kosten in Rechnung gestellt.
• Warnung: Wenn Ihr GMSPlace-Objekt diese Felder nicht enthält, wird Ihnen die SKU für Basisdaten nochmals in Rechnung gestellt. Die restlichen Öffnungszeiten werden über die Place Details Enterprise-SKU abgerechnet. Wenn Sie isOpenWithRequest in Ihrem Projekt verwenden, empfehlen wir Ihnen, die erforderlichen Ortsdetails abzurufen.

Beispiel: GMSPlaceIsOpenWithRequest-Anfrage stellen

Im folgenden Beispiel wird gezeigt, wie eine GMSPlaceIsOpenWithRequest in einem vorhandenen GMSPlace-Objekt initialisiert wird.

SwiftObjective-CGooglePlacesSwift

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

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

          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
          }
          

Erforderliche Parameter

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

• Feldliste

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

  Geben Sie mindestens eines der folgenden Felder an:

  • Die folgenden Felder lösen die SKU „Nearby Search Pro“ 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 SKU „Nearby Search Enterprise Plus“ 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 GMSPlace-Objekt, das von einer Anfrage zurückgegeben wird, die Felder name und placeID enthält:

  SwiftObjective-CPlaces Swift SDK for iOS (Vorabversion)
  // Specify the place data types to return.
  let fields: [GMSPlaceProperty] = [.placeID, .name]
          

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

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

• locationRestriction

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

Optionale Parameter

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

• includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

  Hier können Sie eine Liste von Typen aus den Typen in Tabelle A angeben, mit der die Suchergebnisse gefiltert werden. In jeder Kategorie für Einschränkungen für Typen können bis zu 50 Typen angegeben werden.

  Hinweis : Die Werte in Tabelle B werden nur in der Antwort zurückgegeben. Werte in Tabelle B können nicht als Filter verwendet werden.

  Ein Ort kann nur einen einen primären Typ aus den Typen haben, die ihm in Tabelle A zugeordnet sind. Der primäre Typ kann beispielsweise "mexican_restaurant" oder "steak_house" sein. Mit includedPrimaryTypes und excludedPrimaryTypes können Sie die Ergebnisse nach dem primären Typ eines Orts filtern.

  Ein Ort kann auch mehrere Typenwerte aus den Typen haben, die ihm in Tabelle A zugeordnet sind. 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 in der Liste der mit einem Ort verknüpften Typen filtern.

  Wenn Sie einen allgemeinen primären Typ angeben, z. B. "restaurant" oder "hotel", kann die Antwort Orte mit einem spezifischeren primären Typ als dem angegebenen enthalten. Sie geben beispielsweise an, dass ein primärer Typ von "restaurant" enthalten sein 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 Einschränkungen des Typs 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 Dienstleistungen an, sind aber nicht in erster Linie als "steak_house" tätig.

  Wenn Sie includedTypes, excludedTypes, includedPrimaryTypes und excludedPrimaryTypes aus der Anfrage auslassen, werden bei der Suche Orte aller Typen innerhalb der Grenzen der Standorteinschränkungen zurückgegeben.

  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 von einer Suche ausgeschlossen werden sollen.

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

  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 einbezogen werden sollen.

  excludedPrimaryTypes

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

  Wenn es Konflikte bei primären Typen gibt, z. B. wenn ein Typ sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes vorkommt, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.

• maxResultCount

  Gibt die maximale Anzahl der zu retournierenden Ortsergebnisse an. Muss zwischen 1 und 20 (Standard) liegen.

• rankPreference

  Die Art des Rankings, die verwendet werden soll. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Kann einer der folgenden Werte sein:

  • .popularity (Standardeinstellung): Die Ergebnisse werden nach ihrer Beliebtheit sortiert.
  • .distance: Die Ergebnisse werden in aufsteigender Reihenfolge nach ihrer Entfernung vom angegebenen Standort sortiert.

• regionCode

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

  Wenn der Ländername des Felds formattedAddress in der Antwort mit dem regionCode übereinstimmt, wird der Ländercode aus formattedAddress weggelassen. Dieser Parameter hat keine Auswirkungen auf adrFormatAddress, in dem der Ländername immer enthalten ist, und auf shortFormattedAddress, in dem er nie enthalten ist.

  Die meisten CLDR-Codes entsprechen den ISO 3166-1-Codes, mit einigen Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für die Entität „Vereinigtes Königreich von Großbritannien und Nordirland“). Der Parameter kann sich auf die Ergebnisse auswirken, die gemäß anwendbarem Recht angezeigt werden.

Zuordnungen in der App anzeigen

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

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

Weitere Informationen finden Sie in der Dokumentation zu Attributionen.