Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Eine „Nearby Search (New)“-Anfrage verwendet die als Kreis angegebene Region für die Suche, definiert durch die Breiten- und Längengradkoordinaten des Kreismittelpunkts sowie den Radius in Metern. Die Anfrage gibt eine Liste übereinstimmender Orte im angegebenen Suchbereich zurück. Jeder Ort wird durch ein GMSPlace-Objekt dargestellt.

Standardmäßig enthält die Antwort Orte aller Typen innerhalb des Suchbereichs. Optional können Sie die Antwort filtern. Geben Sie dazu eine Liste von Ortstypen an, die explizit in die Antwort ein- oder ausgeschlossen werden sollen. So können Sie beispielsweise festlegen, dass nur Orte mit dem Typ „Restaurant“, „Bäckerei“ oder „Café“ in die Antwort aufgenommen oder alle Orte des Typs „Schule“ ausgeschlossen werden.

„Nearby Search (neu)“-Anfragen

Stellen Sie eine Nearby Search-Anfrage, indem Sie GMSPlacesClient searchNearbyWithRequest: aufrufen und ein GMSPlaceSearchNearbyRequest-Objekt übergeben, das die Anfrageparameter und eine Callback-Methode vom Typ GMSPlaceSearchNearbyResultCallback für die Verarbeitung der Antwort definiert.

Das Objekt GMSPlaceSearchNearbyRequest 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. Sie wird auch als Feldmaske bezeichnet und ist durch GMSPlaceProperty definiert. Wenn Sie mindestens ein Feld in der Feldliste nicht angeben oder die Feldliste auslassen, gibt der Aufruf einen Fehler zurück.
  • Die Standortbeschränkung, d. h. der Kreis, mit dem das Suchgebiet definiert wird.

In diesem Beispiel für eine „Nearby Search“-Anfrage wird angegeben, dass die GMSPlace-Antwortobjekte 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.

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

GooglePlacesSwift

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 mit einem GMSPlace-Objekt pro übereinstimmendem Ort zurück.

Zusammen mit den Datenfeldern enthält das GMSPlace-Objekt in der Antwort die folgenden Mitgliederfunktionen:

  • isOpen berechnet, ob ein Ort zu diesem Zeitpunkt geöffnet ist.
  • isOpenAtDate berechnet, ob ein Ort an einem bestimmten Datum geöffnet ist.

Erforderliche Parameter

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

  • Feldliste

    Wenn Sie Ortsdetails anfordern, müssen Sie die Daten angeben, die im GMSPlace-Objekt für den Ort als Feldmaske zurückgegeben werden sollen. Übergeben Sie zum Definieren der Feldmaske ein Wertearray aus GMSPlaceProperty an das GMSPlaceSearchNearbyRequest-Objekt. Die Maskierung von Feldern hat sich bewährt, damit keine unnötigen Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und Gebühren vermeiden.

    Geben Sie eines oder mehrere der folgenden Felder an:

    • Die folgenden Felder lösen die SKU Nearby Search (Basic) aus:

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

    • Die folgenden Felder lösen die SKU Nearby Search (Advanced) aus:

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

    • Die folgenden Felder lösen die SKU Nearby Search (Preferred) 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:

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

    GooglePlacesSwift

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

  • locationRestriction

    Ein GMSPlaceLocationRestriction-Objekt, das die zu durchsuchende Region als Kreis definiert, definiert durch Mittelpunkt und Radius in Metern. Der Umkreis muss zwischen 0,0 und 50000,0 (jeweils einschließlich) liegen. Der Standardradius ist 0,0. Sie müssen ihn in Ihrer Anfrage auf einen Wert größer als 0,0 festlegen.

Optionale Parameter

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

  • „includedTypes“/„excludedTypes“, „includedPrimaryTypes/excludedPrimaryTypes“

    Zur Angabe einer Liste mit Typen aus dem Typ Tabelle A, der zum Filtern der Suchergebnisse verwendet wird In jeder Typeinschränkungskategorie können bis zu 50 Typen angegeben werden.

    Ein Ort kann nur einen einzigen primären Typ aus dem zugehörigen Typ 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 Ortes zu filtern.

    Ein Ort kann auch mehrere Typwerte aus den Typen Tabelle A haben. Ein Restaurant könnte 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 bei einer Suche mehrere Typeinschränkungen angegeben werden, werden nur Orte zurückgegeben, die alle Einschränkungen erfüllen. Wenn du beispielsweise {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} angibst, bieten die zurückgegebenen Orte "restaurant"-bezogene Dienste an, werden aber nicht hauptsächlich als "steak_house" verwendet.

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

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

    Wenn Typen in Konflikt stehen, 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 bei einer Suche ausgeschlossen werden sollen.

    Wenn in Konflikt stehende Primärtypen vorhanden sind, z. B. ein Typ sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.

  • maxResultCount

    Gibt die maximale Anzahl der Ortsergebnisse an, die zurückgegeben werden sollen. Der Wert muss zwischen 1 und 20 (Standardwert) liegen.

  • rankPreference

    Die zu verwendende Rangfolgenart. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Folgende Werte sind möglich:

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

  • regionCode

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

    Wenn der Ländername des Felds formattedAddress in der Antwort mit regionCode übereinstimmt, wird der Ländercode bei formattedAddress weggelassen. 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 lautet beispielsweise „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ lautet (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“). Der Parameter kann sich gemäß anwendbarem Recht auf Ergebnisse auswirken.

Zuordnungen in der App anzeigen

Wenn in Ihrer App Informationen aus GMSPlacesClient angezeigt werden, z. B. Fotos und Rezensionen, müssen auch die erforderlichen Quellenangaben vorhanden sein.

Beispielsweise enthält das Attribut reviews des GMSPlacesClient-Objekts ein Array mit bis zu fünf GMSPlaceReview-Objekten. Jedes GMSPlaceReview-Objekt kann Quellenangaben und Autoreninformationen enthalten. Wenn Sie die Rezension in Ihrer App präsentieren, müssen Sie auch die Quellenangabe oder den Autor angeben.

Weitere Informationen finden Sie in der Dokumentation zu Attributionen.