Text Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Entwickler im Europäischen Wirtschaftsraum (EWR)

Bei Verwendung von „Text Search (New)“ werden Informationen zu verschiedenen Orten auf Grundlage eines Textstrings zurückgegeben, z. B. „Pizza in München“, „Schuhgeschäfte in der Nähe von Hamburg“ oder „Hauptstraße 123“. Der Dienst gibt eine Liste mit Orten zurück, die dem Textstring und ggf. der festgelegten Standortgewichtung entsprechen.

Neben den erforderlichen Parametern unterstützt „Text Search (New)“ die Verfeinerung von Abfragen mit optionalen Parametern, um bessere Ergebnisse zu erzielen.

Liste von Orten per Textsuche abrufen

Stellen Sie eine „Text Search“-Anfrage, indem Sie GMSPlacesClient searchByTextWithRequest: aufrufen und ein GMSPlaceSearchByTextRequest Objekt übergeben, das die Anfrageparameter und eine Callback-Methode vom Typ GMSPlaceSearchByTextResultCallback definiert, um die Antwort zu verarbeiten.

Das -Objekt gibt alle erforderlichen und optionalen Parameter für die Anfrage an.GMSPlaceSearchByTextRequest 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 Textabfrage.

Diese Beispielanfrage für die Textsuche gibt an, dass die GMSPlace-Objekte in der Antwort den Ortsnamen und die Orts-ID für jedes GMSPlace-Objekt in den Suchergebnissen enthalten sollen. Außerdem wird die Antwort so gefiltert, dass nur Orte vom Typ „Restaurant“ zurückgegeben werden.

Places SDK for Swift

let restriction = GMSPlaceRectangularLocationOption(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [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().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

„Text Search“-Antworten

Die Text Search API gibt ein Array von Übereinstimmungen in Form von GMSPlace Objekten zurück, wobei jedes GMSPlace Objekt einem übereinstimmenden Ort entspricht.

Status „Geöffnet“ abrufen

Das GMSPlacesClient-Objekt 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. Die Angabe basiert auf der im Aufruf angegebenen Zeit.

Für diese Methode wird ein einzelnes Argument vom Typ GMSPlaceIsOpenWithRequest verwendet, 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 (Swift)-Objekt, das die Zeit angibt, die Sie prüfen möchten. Wenn keine Zeit angegeben ist, wird die aktuelle Zeit verwendet.
  • Eine GMSPlaceOpenStatusResponseCallback-Methode zur Verarbeitung 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 Place-Objekt angegeben sind oder Sie eine Orts-ID übergeben, werden sie mit GMSPlacesClient GMSFetchPlaceRequest: abgerufen.

Antwort von isOpenWithRequest

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

Sprache Wert, wenn geöffnet Wert, wenn geschlossen Wert, wenn Status unbekannt
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 abgerechnet. Die restlichen Öffnungszeiten werden unter der SKU „Place Details Enterprise“ abgerechnet.
  • Wenn Ihr GMSPlace-Objekt diese Felder bereits aus einer vorherigen Anfrage enthält, werden sie nicht noch einmal in Rechnung gestellt.

Beispiel: GMSPlaceIsOpenWithRequest-Anfrage stellen

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

Places SDK for 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
            }
          }];

Seitenumbruch

Die Textsuche bietet ein Paginierungsobjekt, den hasNextPage booleschen Wert, der in der ersten Antwort auf einen „Text Search“-Aufruf zurückgegeben wird. Wenn eine nächste Seite verfügbar ist, können Sie sie mit der fetchNextPage() Funktion laden.

Im folgenden Beispiel wird gezeigt, wie Sie prüfen, ob eine nächste Seite verfügbar ist, und sie dann laden.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

Erforderliche Parameter

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

  • Feldliste

    Geben Sie an, welche Eigenschaften der Ortsdaten zurückgegeben werden sollen. Übergeben Sie eine Liste von GMSPlace Eigenschaften, die die zurückzugebenden Datenfelder angeben. Wenn Sie die Feld maske weglassen, gibt die Anfrage einen Fehler zurück.

    Feldlisten sind eine gute Design-Best Practice, um zu verhindern, dass unnötige 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 „Text Search Essentials (ID Only)“ aus:

      GMSPlacePropertyPlaceID

    • Die folgenden Felder lösen die SKU „Text Search Pro“ aus:

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

    • Die folgenden Felder lösen die SKU „Text Search Enterprise“ aus:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Die folgenden Felder lösen die SKU „Text Search Enterprise Plus“ aus:

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

  • textQuery

    Der Textstring, nach dem gesucht werden soll, z. B. „Restaurant“, „Hauptstraße 60 “ oder „Bester Ort in San Francisco“.

Optionale Parameter

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

  • includedType

    Beschränkt die Ergebnisse auf Orte, die dem in Tabelle A angegebenen Typ entsprechen. Es kann nur ein Typ angegeben werden. Beispiel:

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    Wenn true, werden nur Orte zurückgegeben, die beim Senden der Anfrage geöffnet haben. Wenn false, werden alle Unternehmen unabhängig vom Status „Geöffnet“ zurückgegeben. Orte, für die in der Google Places-Datenbank keine Öffnungszeiten angegeben sind, werden zurückgegeben, wenn Sie diesen Parameter auf false setzen.

  • isStrictTypeFiltering

    Wird mit dem Parameter includeType verwendet. Wenn auf true gesetzt, werden nur Orte zurückgegeben, die den in includeType angegebenen Typen entsprechen. Wenn „false“ (Standardeinstellung), kann die Antwort Orte enthalten, die nicht den angegebenen Typen entsprechen.

  • locationBias

    Gibt einen Bereich für die Suche an. Dieser Standort dient als Gewichtung. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Standorts zurückgegeben werden können, einschließlich Ergebnissen außerhalb des angegebenen Bereichs.

    Sie können locationRestriction oder locationBias, aber nicht beide angeben. locationRestriction gibt den Bereich an, in dem sich die Ergebnisse befinden müssen, und locationBias gibt den Bereich an, in dessen Nähe sich die Ergebnisse befinden müssen, aber außerhalb des Bereichs liegen können.

    Geben Sie die Region als rechteckigen Darstellungsbereich oder als Kreis an.

    • Ein Kreis wird durch einen Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 liegen (einschließlich). Der Standardradius ist 0,0. Beispiel:

      let request = SearchByTextRequest()
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

    • Ein Rechteck ist ein Darstellungsbereich mit Breiten- und Längengrad, der durch zwei diagonal gegenüberliegende Tief- und Hochpunkte dargestellt wird. Der Tiefpunkt markiert die südwestliche Ecke des Rechtecks und der Hochpunkt die nordöstliche Ecke.

      Ein Darstellungsbereich gilt als geschlossene Region, d. h., er umfasst auch seine Grenze. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen (einschließlich) und die Längengradgrenzen müssen zwischen -180 und 180 Grad liegen (einschließlich):

      • Wenn low = high, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude, wird der Längengradbereich umgekehrt (der Darstellungsbereich überschreitet die 180-Grad-Linie).
      • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad, umfasst der Darstellungsbereich alle Längengrade.
      • Wenn low.longitude = 180 Grad und high.longitude = -180 Grad, ist der Längengradbereich leer.
      • Wenn low.latitude > high.latitude, ist der Breitengradbereich leer.

  • locationRestriction

    Gibt einen Bereich für die Suche an. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Geben Sie die Region als rechteckigen Darstellungsbereich an. Informationen zum Definieren des Darstellungsbereichs finden Sie in der Beschreibung von locationBias.

    Sie können locationRestriction oder locationBias, aber nicht beide angeben. locationRestriction gibt den Bereich an, in dem sich die Ergebnisse befinden müssen, und locationBias gibt den Bereich an, in dessen Nähe sich die Ergebnisse befinden müssen, aber außerhalb des Bereichs liegen können.

  • maxResultCount

    Gibt die maximale Anzahl der zurückzugebenden Orts-Ergebnisse an. Muss zwischen 1 und 20 (Standardwert) liegen (einschließlich).

  • minRating

    Beschränkt die Ergebnisse auf Orte, deren durchschnittliche Nutzerbewertung größer oder gleich diesem Grenzwert ist. Die Werte müssen zwischen 0,0 und 5,0 liegen (einschließlich) und in Schritten von 0,5 angegeben werden. Beispiel: 0, 0,5, 1,0, ..., 5,0 (einschließlich). Die Werte werden auf die nächste 0,5 aufgerundet. Ein Wert von 0,6 schließt beispielsweise alle Ergebnisse mit einer Bewertung unter 1,0 aus.

  • priceLevels

    Beschränken Sie die Suche auf Orte, die mit bestimmten Preisklassen gekennzeichnet sind. Standardmäßig sind alle Preisklassen ausgewählt.

    Geben Sie ein Array mit einem oder mehreren Werten an, die durch PriceLevel definiert sind.

    Beispiel:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    Gibt an, wie die Ergebnisse in der Antwort basierend auf dem Typ der Anfrage sortiert werden:

    • Bei einer kategorialen Anfrage wie "Restaurants in München" ist .relevance (Ergebnisse nach Suchrelevanz sortieren) die Standardeinstellung. Sie können rankPreference auf .relevance oder .distance (Ergebnisse nach Entfernung sortieren) setzen.
    • Bei einer nicht kategorialen Anfrage wie "Mountain View, CA" empfehlen wir , rankPreference nicht festzulegen.

  • regionCode

    Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als zweistelliger CLDR-Code. Dieser Parameter kann auch die Suchergebnisse beeinflussen. Es gibt keinen Standardwert.

    Wenn der Ländername des Adressfelds in der Antwort mit dem Regionscode übereinstimmt, wird der Ländercode aus der Adresse entfernt.

    Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs ist „uk“ (.co.uk) und der ISO 3166-1-Code „gb“ (technisch für die Einheit „Vereinigtes Königreich Großbritannien und Nordirland“). Der Parameter kann sich aufgrund geltenden Rechts auf die Ergebnisse auswirken.

  • shouldIncludePureServiceAreaBusinesses

    Wenn true, werden Unternehmen ohne festen Standort in einem Einzugsgebiet in den Suchergebnissen zurückgegeben. Unternehmen ohne festen Standort in einem Einzugsgebiet sind Unternehmen, die Kunden vor Ort besuchen oder direkt beliefern, aber an ihrer Geschäftsadresse keine Kunden empfangen.

    Beispiel:

    Places SDK for Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

Zuordnungen in der App anzeigen

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

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

Weitere Informationen finden Sie in der Dokumentation zu Zuordnungen.