Text Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Entwickler im Europäischen Wirtschaftsraum (EWR)

Bei einer Textsuche werden Informationen über eine Gruppe von Orten auf Grundlage eines Strings zurückgegeben. Beispiele: „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.

Der Dienst ist besonders nützlich, um mehrdeutige Adressanfragen in einem automatisierten System zu stellen. Nicht adressbezogene Komponenten des Strings können sowohl mit Unternehmen als auch mit Adressen übereinstimmen. Beispiele für mehrdeutige Adressanfragen sind schlecht formatierte Adressen oder Anfragen, die keine Adresskomponenten enthalten, z. B. Unternehmensnamen. Bei Anfragen wie den ersten beiden Beispielen werden möglicherweise keine Ergebnisse zurückgegeben, sofern kein Standort (z. B. Region, Standortbeschränkung oder Standortbias) festgelegt ist.

„10 High Street, UK“ oder „123 Main Street, US“ Es gibt mehrere „High Street“-Straßen im Vereinigten Königreich und mehrere „Main Street“-Straßen in den USA. Die Abfrage liefert nur dann die gewünschten Ergebnisse, wenn eine Standortbeschränkung festgelegt ist.
„Kettenrestaurant New York“ Mehrere Standorte einer Restaurantkette in New York; keine Adresse oder nicht einmal ein Straßenname.
„10 High Street, Escher UK“ oder „123 Main Street, Pleasanton US“ Es gibt nur eine „High Street“ in der britischen Stadt Escher und nur eine „Main Street“ in der US-amerikanischen Stadt Pleasanton, Kalifornien.
„UniqueRestaurantName New York“ Es gibt nur ein Unternehmen mit diesem Namen in New York. Es ist keine Straßenadresse erforderlich, um es zu unterscheiden.
„Pizzerien in New York“ Diese Anfrage enthält eine Standortbeschränkung und „Pizzerien“ ist ein genau definierter Ortstyp. Es werden mehrere Ergebnisse zurückgegeben.
„+1 514-670-8700“

Diese Anfrage enthält eine Telefonnummer. Es werden mehrere Ergebnisse für Orte zurückgegeben, die mit dieser Telefonnummer verknüpft sind.

Liste von Orten per Textsuche abrufen

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

Das GMSPlaceSearchByTextRequest-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 Textanfrage.

In dieser Beispielanfrage für die Textsuche wird angegeben, dass die Antwortobjekte GMSPlace den Ortsnamen und die Orts-ID für jedes GMSPlace-Objekt in den Suchergebnissen enthalten. Außerdem wird die Antwort so gefiltert, dass nur Orte vom Typ „restaurant“ zurückgegeben werden.

Places Swift SDK

let restriction = RectangularLocationRestriction(
      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 es für jeden passenden Ort ein GMSPlace-Objekt 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 GMSPlaceSearchByTextRequest-Objekt, um die erforderlichen Parameter für die Suche anzugeben.

  • Feldliste

    Geben Sie an, welche Eigenschaften von Ortsdaten zurückgegeben werden sollen. Übergeben Sie eine Liste von GMSPlace-Attributen, die die zurückzugebenden Datenfelder angeben. Wenn Sie die Feldmaske weglassen, wird bei der Anfrage ein Fehler zurückgegeben.

    Mit Feldlisten 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 Text Search Essentials ID Only-SKU aus:

      GMSPlacePropertyPlaceID

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

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

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Die folgenden Felder lösen die Text Search Enterprise Plus-SKU 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 „Sehenswürdigkeiten in San Francisco“.

Optionale Parameter

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

  • includedType

    Damit werden die Ergebnisse auf Orte beschränkt, die dem angegebenen Typ entsprechen, der in Tabelle A definiert ist. Es kann nur ein Typ angegeben werden. Beispiel:

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

  • isOpenNow

    Bei 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 festlegen.

  • isStrictTypeFiltering

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

  • locationBias

    Gibt einen Bereich für die Suche an. Dieser Ort dient als Bias. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Orts zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs.

    Sie können locationRestriction oder locationBias angeben, aber nicht beide. locationRestriction gibt die Region an, in der sich die Ergebnisse befinden müssen, und locationBias die Region, in deren Nähe sich die Ergebnisse befinden müssen, aber außerhalb des Gebiets liegen können.

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

    • Ein Kreis wird durch den Mittelpunkt und den Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 liegen (jeweils 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 für Breiten- und Längengrad, der durch zwei diagonal gegenüberliegende niedrige und hohe Punkte dargestellt wird. Der Tiefpunkt markiert die südwestliche Ecke des Rechtecks und der Hochpunkt die nordöstliche Ecke.

      Ein Darstellungsbereich gilt als geschlossener Bereich, d. h., er umfasst auch seine Grenze. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen (einschließlich), und die Grenzen für den Längengrad müssen zwischen -180 und 180 Grad liegen (einschließlich):

      • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude, wird der Längengradbereich umgekehrt (der Darstellungsbereich überschreitet die 180-Grad-Längengradlinie).
      • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad ist, umfasst der Darstellungsbereich alle Längengrade.
      • Wenn low.longitude = 180 Grad und high.longitude = -180 Grad ist, 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 Viewports finden Sie in der Beschreibung von locationBias.

    Sie können locationRestriction oder locationBias angeben, aber nicht beide. locationRestriction gibt die Region an, in der sich die Ergebnisse befinden müssen, und locationBias die Region, in deren Nähe sich die Ergebnisse befinden müssen, aber außerhalb des Gebiets liegen können.

  • maxResultCount

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

  • minRating

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

  • priceLevels

    Schränken Sie die Suche auf Orte ein, die mit bestimmten Preisniveaus gekennzeichnet sind. Standardmäßig sind alle Preisniveaus ausgewählt.

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

    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 eingestuft werden:

    • Bei einer kategorischen Anfrage wie „Restaurants in New York City“ ist .relevance (Ergebnisse nach Suchrelevanz sortieren) die Standardeinstellung. Sie können rankPreference auf .relevance oder .distance (Ergebnisse nach Entfernung sortieren) festlegen.
    • Bei einer nicht kategorischen Anfrage wie „Mountain View, CA“ empfehlen wir, rankPreference nicht festzulegen.

  • regionCode

    Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code. Dieser Parameter kann sich auch auf die Suchergebnisse auswirken. 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. 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.

  • shouldIncludePureServiceAreaBusinesses

    Wenn true, werden in den Suchergebnissen nur Unternehmen mit Dienstleistungsgebiet zurückgegeben. Ein reines Unternehmen ohne festen Standort in einem Einzugsgebiet ist ein Unternehmen, das Kunden vor Ort besucht oder einen Lieferservice hat, aber an seiner Geschäftsadresse keine Kunden empfängt.

    Beispiel:

    Places Swift SDK

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