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.

Zusätzlich zu 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

Wenn Sie eine Text Search-Anfrage stellen möchten, rufen Sie GMSPlacesClient searchByTextWithRequest: auf und übergeben Sie ein GMSPlaceSearchByTextRequest-Objekt, 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 als Feldmaske bezeichnet, wie durch GMSPlaceProperty definiert. Wenn Sie nicht mindestens ein Feld in der Feldliste angeben oder die Feldliste weglassen, gibt der Aufruf einen Fehler zurück.
  • Die Textabfrage.

In dieser Beispielanfrage für die Textsuche wird angegeben, 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 Swift SDK

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 pro übereinstimmendem Ort ein GMSPlace-Objekt enthalten ist.

Status „Geöffnet“ abrufen

Das Objekt GMSPlacesClient enthält eine Memberfunktion 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 Funktionsaufruf 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 Place Details.
  • Ein optionales NSDate- (Obj-C) oder Date-Objekt (Swift), 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 Methode GMSPlaceIsOpenWithRequest müssen die folgenden Felder im Objekt GMSPlace festgelegt werden:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Wenn diese Felder nicht im Place-Objekt enthalten sind oder Sie eine Orts-ID übergeben, werden sie mit der Methode 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, wenn geöffnet Wert, wenn geschlossen Wert, wenn 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 SKU „Basic Data“ abgerechnet. Die restlichen Öffnungszeiten werden über die 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 wird gezeigt, wie ein GMSPlaceIsOpenWithRequest in einem vorhandenen GMSPlace-Objekt initialisiert wird.

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

Seitenumbruch

Die Textsuche stellt ein Seitenumbruchobjekt bereit, den booleschen Wert hasNextPage, 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 Funktion fetchNextPage() laden.

Im folgenden Beispiel wird gezeigt, wie Sie prüfen, ob eine nächste Seite verfügbar ist, und diese Seite 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

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

  • Feldliste

    Geben Sie an, welche Ortsdatenattribute zurückgegeben werden sollen. Übergeben Sie eine Liste von GMSPlace-Properties, in denen die zurückzugebenden Datenfelder angegeben sind. Wenn Sie die Feldmaske weglassen, gibt die Anfrage einen Fehler zurück.

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

      GMSPlacePropertyPlaceID

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

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

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

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

    • 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

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

  • textQuery

    Der Textstring, nach dem gesucht werden soll, z. B. „Restaurant“, „Hauptstraße 60“ oder „Sehenswürdigkeiten in Berlin“.

Optionale Parameter

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

  • includedType

    Damit werden die Ergebnisse auf Orte eingeschränkt, 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 die Orte zurückgegeben, die beim Senden der Anfrage geöffnet haben. Wenn false, werden alle Unternehmen unabhängig vom Öffnungsstatus zurückgegeben. Wenn Sie diesen Parameter auf false festlegen, werden auch Orte zurückgegeben, für die in der Google Places-Datenbank keine Öffnungszeiten hinterlegt sind.

  • isStrictTypeFiltering

    Wird mit dem Parameter includeType verwendet. Wenn der Wert auf true festgelegt ist, werden nur Orte zurückgegeben, die den von includeType angegebenen Typen entsprechen. Wenn der Wert „false“ ist (Standard), 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 angeben, aber nicht beide. Mit locationRestriction wird die Region angegeben, in der die Ergebnisse liegen müssen. Mit locationBias wird die Region angegeben, in deren Nähe die Ergebnisse liegen müssen, aber auch 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. Der Standardradius beträgt 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 Höchstpunkt die nordöstliche Ecke.

      Ein Darstellungsbereich gilt als geschlossene Region, d. h., er schließt seine Grenze ein. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen, die Grenzen für den Längengrad zwischen -180 und 180 Grad:

      • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude, wird der Längengradbereich invertiert (der Darstellungsbereich kreuzt den 180. Längengrad).
      • 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 Darstellungsbereichs finden Sie in der Beschreibung von locationBias.

    Sie können locationRestriction oder locationBias angeben, aber nicht beide. Mit locationRestriction wird die Region angegeben, in der die Ergebnisse liegen müssen. Mit locationBias wird die Region angegeben, in deren Nähe die Ergebnisse liegen müssen, aber auch außerhalb des Bereichs liegen können.

  • maxResultCount

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

  • minRating

    Beschränkt die Ergebnisse auf diejenigen, deren durchschnittliche Nutzerbewertung größer oder gleich diesem Limit 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. Die Werte werden auf die nächsten 0,5 aufgerundet. Beispiel: Ein Wert von 0,6 entfernt alle Ergebnisse mit einer Bewertung von weniger als 1,0.

  • priceLevels

    Schränken Sie die Suche auf Orte ein, die mit bestimmten Preisstufen gekennzeichnet sind. Standardmäßig sind alle Preisstufen 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 Abfragetyp sortiert werden:

    • Bei einer kategorischen Suchanfrage 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 Abfrage 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 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 in der Adresse weggelassen.

    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 „uk“ (.co.uk), der ISO-3166-1-Code dagegen „gb“ (technisch gesehen für das Vereinigte Königreich Großbritannien und Nordirland). Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.

  • shouldIncludePureServiceAreaBusinesses

    Wenn true, werden in den Suchergebnissen reine Unternehmen ohne festen Standort zurückgegeben. Ein Unternehmen ohne festen Standort in einem Einzugsgebiet ist ein Unternehmen, das Kunden vor Ort besucht oder direkt beliefert, 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 über GMSPlacesClient abgerufen wurden, z. B. Fotos und Rezensionen, müssen auch die erforderlichen Quellenangaben eingeblendet werden.

Beispiel: Das Attribut reviews des Objekts GMSPlacesClient enthält 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.