Automatische Vervollständigung (neu)

Plattform auswählen: Android iOS JavaScript Webdienst
Entwickler im Europäischen Wirtschaftsraum (EWR)

Einführung

Autocomplete (New) ist ein Webdienst, der als Antwort auf eine HTTP-Anfrage Ortsvorschläge und Suchvorschläge zurückgibt. Geben Sie in der Anfrage einen Suchstring und geografische Grenzen an, die den Suchbereich einschränken.

Autocomplete (New) findet Übereinstimmungen mit vollständigen Wörtern und Teilstrings der Eingabe, sodass sich Ortsnamen, Adressen und Plus Codes zuordnen lassen. Anwendungen können Abfragen senden, während der Nutzer tippt, und schon bei der Eingabe Orts- und Suchvorschläge ausgeben.

Die Antwort von „Automatische Vervollständigung (New)“ kann zwei Arten von Vervollständigungen enthalten:

  • Ortsvorschläge: Orte wie Unternehmen, Adressen und POIs, die auf dem angegebenen Eingabetextstring und dem Suchbereich basieren. Ortsvorschläge werden standardmäßig zurückgegeben.
  • Suchvorschläge: Abfragestrings, die mit dem eingegebenen Textstring und dem Suchbereich übereinstimmen. Suchvorschläge werden standardmäßig nicht zurückgegeben. Verwenden Sie den Anfrageparameter includeQueryPredictions, um der Antwort Suchvorschläge hinzuzufügen.

Sie rufen beispielsweise Autocomplete (New) mit einem String auf, der eine unvollständige Nutzereingabe enthält, z. B. „Sicilian piz“, und beschränken den Suchbereich auf San Francisco, Kalifornien. Die Antwort enthält dann eine Liste mit Ortsvorschlägen, die dem Suchstring und dem Suchbereich entsprechen, z. B. das Restaurant „Sicilian Pizza Kitchen“, sowie Details zum Ort.

Die zurückgegebenen Ortsvorschläge sollen dem Nutzer angezeigt werden, um ihm die Auswahl des gewünschten Orts zu erleichtern. Sie können eine Place Details (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen Ortsvorschlägen zu erhalten.

Die Antwort kann auch eine Liste von Suchvorschlägen enthalten, die dem Suchstring und dem Suchbereich entsprechen, z. B. „Sizilianische Pizza und Pasta“. Jede Suchanfragenvervollständigung in der Antwort enthält das Feld text mit einem empfohlenen Suchstring für die Textsuche. Verwenden Sie diesen String als Eingabe für Text Search (New), um eine detailliertere Suche durchzuführen.

Mit dem APIs Explorer können Sie Liveanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:

Autocomplete (New)-Anfragen

Eine Autocomplete (New)-Anfrage ist eine HTTP-POST-Anfrage an eine URL im folgenden Format:

https://places.googleapis.com/v1/places:autocomplete

Übergeben Sie alle Parameter im JSON-Anfragetext oder in Headern als Teil der POST-Anfrage. Beispiel:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Unterstützte Parameter

Parameter

Beschreibung

input*

Textstring, nach dem gesucht werden soll (vollständige Wörter, Teilstrings, Ortsnamen, Adressen, Plus Codes).

FieldMask (HTTP-Header)

Durch Kommas getrennte Liste, in der angegeben wird, welche Felder in der Antwort zurückgegeben werden sollen.

includedPrimaryTypes

Beschränkt die Ergebnisse auf Orte, die einem von bis zu fünf angegebenen primären Typen entsprechen.

includePureServiceAreaBusinesses

Wenn „true“, werden Unternehmen ohne physischen Standort (Unternehmen ohne festen Standort in einem Einzugsgebiet) einbezogen. Die Standardeinstellung ist "false".

includeQueryPredictions

Wenn „true“, werden sowohl Orts- als auch Suchvorschläge in die Antwort aufgenommen. Die Standardeinstellung ist "false".

includedRegionCodes

Array mit bis zu 15 zweistelligen Ländercodes, auf die die Ergebnisse beschränkt werden sollen.

inputOffset

Nullbasierter Unicode-Zeichen-Offset der Cursorposition innerhalb des Eingabestrings, der die Vervollständigungen beeinflusst. Die Standardeinstellung ist die Eingabelänge.

languageCode

Bevorzugte Sprache (IETF BCP-47-Code) für Ergebnisse. Die Standardeinstellung ist der Accept-Language-Header oder „en“.

locationBias

Gibt einen Bereich (Kreis oder Rechteck) an, auf den die Suchergebnisse ausgerichtet werden sollen. Ergebnisse außerhalb des Bereichs sind zulässig. Kann nicht mit „locationRestriction“ verwendet werden.

locationRestriction

Gibt einen Bereich (Kreis oder Rechteck) an, auf den die Suchergebnisse beschränkt werden sollen. Ergebnisse außerhalb dieses Bereichs werden ausgeschlossen. Kann nicht mit „locationBias“ verwendet werden.

origin

Ausgangspunkt (Breitengrad, Längengrad), der zur Berechnung der Luftlinie (distanceMeters) zu vorhergesagten Zielen verwendet wird.

regionCode

Regionscode, der zum Formatieren der Antwort und zum Beeinflussen von Vorschlägen verwendet wird (z.B. „uk“, „fr“).

sessionToken

Vom Nutzer generierter String, um Autocomplete-Aufrufe zu Abrechnungszwecken in einer Sitzung zu gruppieren.

* Pflichtfeld

Informationen zur Antwort

Autocomplete (New) gibt ein JSON-Objekt als Antwort zurück. Die Antwort sieht so aus:

  • Das Array suggestions enthält alle vorhergesagten Orte und Suchanfragen, sortiert nach ihrer Relevanz. Jeder Ort wird durch ein placePrediction-Feld und jede Abfrage durch ein queryPrediction-Feld dargestellt.
  • Ein placePrediction-Feld enthält detaillierte Informationen zu einer einzelnen Ortsvervollständigung, einschließlich der Orts-ID und der Textbeschreibung.
    • Damit die Textbeschreibung einer Ortsvorhersage besser mit der Nutzereingabe im Parameter input übereinstimmt, kann sie alternative Namen für Orte, Straßen und andere Adresskomponenten enthalten. Diese alternativen Namen können sich von den Namen unterscheiden, die in den Feldern displayName und „address“ der Place Details-Ergebnisse für dieselbe Orts-ID zurückgegeben werden.
    • In diesem Kontext können alternative Namen für einige Orte in einer anderen Sprache als der im Parameter languageCode angegebenen Sprache sein, je nachdem, welche Namen besser zur Nutzereingabe passen.
  • Ein queryPrediction-Feld enthält detaillierte Informationen zu einer einzelnen Abfragevorhersage.

Das vollständige JSON-Objekt hat folgendes Format:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Erforderliche Parameter

Eingabe

Der Textstring, nach dem gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Der Autocomplete-Dienst (New) gibt mögliche Übereinstimmungen basierend auf diesem String zurück und sortiert die Ergebnisse nach ihrer Relevanz.

Optionale Parameter

FieldMask

Geben Sie die Liste der Felder an, die in der Antwort zurückgegeben werden sollen, indem Sie eine Antwortfeldmaske erstellen. Übergeben Sie die Antwortfeldmaske mit dem HTTP-Header X-Goog-FieldMask an die Methode.

Geben Sie eine durch Kommas getrennte Liste der Vorschlagsfelder an, die zurückgegeben werden sollen. Beispiel: Zum Abrufen von suggestions.placePrediction.text.text und suggestions.queryPrediction.text.text des Vorschlags.

  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

Verwenden Sie *, um alle Felder abzurufen.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

Wenn true, werden Unternehmen zurückgegeben, die voraussichtlich in Zukunft eröffnet werden. Die Standardeinstellung ist false.

includedPrimaryTypes

Ein Ort kann nur einen einzigen primären Typ aus den in Tabelle A oder Tabelle B aufgeführten Typen haben. Der primäre Typ könnte beispielsweise "mexican_restaurant" oder "steak_house" sein.

Standardmäßig gibt die API alle Orte basierend auf dem Parameter input zurück, unabhängig vom primären Typwert, der dem Ort zugeordnet ist. Sie können die Ergebnisse auf einen oder mehrere bestimmte primäre Typen beschränken, indem Sie den Parameter includedPrimaryTypes übergeben.

Mit diesem Parameter können Sie bis zu fünf Typwerte aus Tabelle A oder Tabelle B angeben. Ein Ort muss mit einem der angegebenen primären Typwerte übereinstimmen, damit er in die Antwort aufgenommen wird.

Dieser Parameter kann stattdessen auch (regions) oder (cities) enthalten. Die Sammlung vom Typ (regions) filtert nach Gebieten oder Bereichen, z. B. Stadtteilen und Postleitzahlen. Mit der Typensammlung (cities) wird nach Orten gefiltert, die von Google als Stadt identifiziert werden.

Die Anfrage wird mit dem Fehler INVALID_REQUEST abgelehnt, wenn:

  • Es wurden mehr als fünf Typen angegeben.
  • Zusätzlich zu (cities) oder (regions) wird ein beliebiger Typ angegeben.
  • Sie haben einen unbekannten Typ angegeben.

includePureServiceAreaBusinesses

Wenn der Wert auf true gesetzt ist, enthält die Antwort Unternehmen, die Kunden direkt besuchen oder beliefern, aber keinen festen Standort haben. Wenn der Wert auf false festgelegt ist, gibt die API nur Unternehmen mit einem physischen Standort zurück.

includeQueryPredictions

Wenn true, enthält die Antwort sowohl Orts- als auch Suchvorschläge. Der Standardwert ist false. Das bedeutet, dass die Antwort nur Ortsvorschläge enthält.

includedRegionCodes

Es werden nur Ergebnisse aus der Liste der angegebenen Regionen berücksichtigt, die als Array mit bis zu 15 ccTLD-Werten („Top-Level-Domain“) mit zwei Zeichen angegeben sind. Wenn sie weggelassen wird, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie die Regionen beispielsweise auf Deutschland und Frankreich:

    "includedRegionCodes": ["de", "fr"]

Wenn Sie sowohl locationRestriction als auch includedRegionCodes angeben, befinden sich die Ergebnisse im Schnittbereich der beiden Einstellungen.

inputOffset

Der nullbasierte Unicode-Zeichen-Offset, der die Cursorposition in input angibt. Die Cursorposition kann beeinflussen, welche Vervollständigungen zurückgegeben werden. Wenn das Feld leer ist, wird standardmäßig die Länge von input verwendet.

languageCode

Die bevorzugte Sprache, in der Ergebnisse zurückgegeben werden sollen. Die Ergebnisse können in verschiedenen Sprachen vorliegen, wenn die in input verwendete Sprache von dem durch languageCode angegebenen Wert abweicht oder wenn für den zurückgegebenen Ort keine Übersetzung aus der Landessprache in languageCode vorhanden ist.

  • Sie müssen IETF BCP-47-Sprachcodes verwenden, um die bevorzugte Sprache anzugeben.
  • Wenn languageCode nicht angegeben ist, verwendet die API den im Header Accept-Language angegebenen Wert. Wenn keines von beiden angegeben ist, wird standardmäßig en verwendet. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück.
  • Die bevorzugte Sprache hat einen geringen Einfluss auf die von der API zurückgegebenen Ergebnisse und die Reihenfolge, in der sie zurückgegeben werden. Dies wirkt sich auch auf die Fähigkeit der API aus, Rechtschreibfehler zu korrigieren.
  • Ortsvorschläge werden je nach Nutzereingabe in der jeweiligen Anfrage unterschiedlich formatiert.
    • Zuerst werden übereinstimmende Begriffe im Parameter input ausgewählt. Dabei werden Namen verwendet, die der im Parameter languageCode angegebenen Spracheinstellung entsprechen, sofern verfügbar. Andernfalls werden Namen verwendet, die am besten zur Nutzereingabe passen.
    • Ortsnamen können mit alternativen Namen formatiert werden, die mit Begriffen im Parameter input übereinstimmen, einschließlich Namen in anderen Sprachen als der im Parameter languageCode angegebenen Sprache.
    • Adressen werden in der Landessprache und, wenn möglich, in einer für den Nutzer lesbaren Schrift formatiert, nachdem übereinstimmende Begriffe ausgewählt wurden, die den Begriffen im Parameter input entsprechen.
    • Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem übereinstimmende Begriffe ausgewählt wurden, die den Begriffen im Parameter input entsprechen. Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die nächstgelegene Übereinstimmung.

locationBias oder locationRestriction

Sie können entweder locationBias oder locationRestriction angeben, um den Suchbereich zu definieren, aber nicht beides. 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.

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

  • locationRestriction

    Gibt einen Bereich für die Suche an. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.

Geben Sie die Region locationBias oder locationRestriction 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 (jeweils einschließlich). Der Standardwert ist 0,0. Für locationRestriction müssen Sie den Radius auf einen Wert größer als 0,0 festlegen. Andernfalls werden keine Ergebnisse zurückgegeben.

    Beispiel:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }
  • Ein Rechteck ist ein Darstellungsbereich mit Breiten- und Längengrad, der durch zwei diagonal gegenüberliegende low- und Höhepunkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossene Region, d. h., er umfasst auch seine Grenze. 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-Grad-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.

    Sowohl low als auch high müssen ausgefüllt sein und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

    Dieser Darstellungsbereich umschließt beispielsweise New York City vollständig:

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

origin

Der Ausgangspunkt, von dem aus die Luftlinie zum Ziel berechnet werden soll (zurückgegeben als distanceMeters). Wenn dieser Wert weggelassen wird, wird die Luftlinie nicht zurückgegeben. Muss als Breiten- und Längengradkoordinaten angegeben werden:

"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

regionCode

Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als zweistelliger Wert der ccTLD („Top-Level-Domain“). Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes. 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).

Vorschläge werden auch basierend auf Regionscodes angepasst. Google empfiehlt, die regionCode entsprechend den regionalen Einstellungen des Nutzers festzulegen.

Wenn Sie einen ungültigen Regionscode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück. Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.

Wenn Sie regionCode festlegen, wird bei Vervollständigungen innerhalb dieser Region möglicherweise der Ländername im Vorschlagstext weggelassen. Das bedeutet, dass structuredFormat.secondaryText möglicherweise nicht vorhanden ist. Achten Sie daher darauf, dass Ihre Anwendung Fälle verarbeitet, in denen secondaryText nicht definiert ist oder fehlt.

sessionToken

Sitzungstokens sind vom Nutzer generierte Strings, mit denen Autocomplete (New)-Aufrufe als „Sitzungen“ erfasst werden. Bei Autocomplete (New) werden Sitzungstokens verwendet, um die Abfrage- und Auswahlphasen einer Nutzeranfrage zur automatischen Vervollständigung zu Abrechnungszwecken zu einer separaten Sitzung zusammenzufassen. Weitere Informationen finden Sie unter Sitzungstokens.

Parameter zum Beeinflussen der Ergebnisse auswählen

Die Parameter von Autocomplete (New) können die Suchergebnisse unterschiedlich beeinflussen. Die folgende Tabelle enthält Empfehlungen zur Verwendung von Parametern basierend auf dem beabsichtigten Ergebnis.
Parameter Nutzungsempfehlung
regionCode Wird gemäß den regionalen Einstellungen des Nutzers festgelegt.
includedRegionCodes Wird festgelegt, um die Ergebnisse auf die Liste der angegebenen Regionen zu beschränken.
locationBias Verwenden Sie diese Option, wenn Ergebnisse in oder um eine Region bevorzugt werden. Definieren Sie die Region gegebenenfalls als den Darstellungsbereich der Karte, die sich der Nutzer ansieht.
locationRestriction Verwenden Sie diese Option nur, wenn Ergebnisse außerhalb einer Region nicht zurückgegeben werden sollen.
origin Verwenden Sie diese Option, wenn die Luftlinie zu jeder Vorhersage gewünscht ist.

Beispiele für Autocomplete (New)

Suche mit „locationRestriction“ auf einen Bereich beschränken

Mit locationRestriction wird der Suchbereich angegeben. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel wird locationRestriction verwendet, um die Anfrage auf einen Kreis mit einem Radius von 5.000 Metern um San Francisco zu beschränken:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Alle Ergebnisse aus den angegebenen Bereichen sind im Array suggestions enthalten:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Sie können auch locationRestriction verwenden, um die Suche auf einen rechteckigen Darstellungsbereich zu beschränken. Im folgenden Beispiel wird die Anfrage auf die Innenstadt von San Francisco beschränkt:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Die Ergebnisse sind im Array suggestions enthalten:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Suche mit „locationBias“ auf einen Bereich eingrenzen

Bei locationBias dient der Standort 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. Im folgenden Beispiel wird die Anfrage auf die Innenstadt von San Francisco ausgerichtet:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Die Ergebnisse enthalten jetzt viel mehr Elemente, einschließlich Ergebnisse außerhalb des Radius von 5.000 Metern:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Sie können auch locationBias verwenden, um die Suche auf einen rechteckigen Darstellungsbereich zu beschränken. Im folgenden Beispiel wird die Anfrage auf die Innenstadt von San Francisco beschränkt:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

In der Antwort werden zwar Suchergebnisse innerhalb des rechteckigen Darstellungsbereichs angezeigt, aufgrund der Gewichtung liegen jedoch einige Ergebnisse außerhalb der definierten Grenzen. Die Ergebnisse sind auch im suggestions-Array enthalten:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

„includedPrimaryTypes“ verwenden

Verwenden Sie den Parameter includedPrimaryTypes, um bis zu fünf Typwerte aus Tabelle A, Tabelle B, nur (regions) oder nur (cities) anzugeben. Ein Ort muss mit einem der angegebenen primären Typwerte übereinstimmen, damit er in die Antwort aufgenommen wird.

Im folgenden Beispiel geben Sie den input-String „Soccer“ an und verwenden den Parameter includedPrimaryTypes, um die Ergebnisse auf Einrichtungen vom Typ "sporting_goods_store" zu beschränken:

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Wenn Sie den Parameter includedPrimaryTypes weglassen, können die Ergebnisse auch Orte eines Typs enthalten, den Sie nicht möchten, z. B. "athletic_field".

Abfragevorhersagen anfordern

Suchvorschläge werden standardmäßig nicht zurückgegeben. Verwenden Sie den Anfrageparameter includeQueryPredictions, um der Antwort Suchvorschläge hinzuzufügen. Beispiel:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Das Array suggestions enthält jetzt sowohl Orts- als auch Suchvorschläge, wie oben unter Informationen zur Antwort beschrieben. Jede Vervollständigung enthält das Feld text mit einem empfohlenen Suchstring für die Textsuche. Sie können eine Text Search (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen vervollständigten Suchanfragen zu erhalten.

Ursprung verwenden

In diesem Beispiel wird origin in der Anfrage als Breiten- und Längengradkoordinaten angegeben. Wenn Sie origin angeben, enthält die Antwort von „Autocomplete (New)“ das Feld distanceMeters mit der Luftlinie von origin zum Ziel. In diesem Beispiel wird der Ursprung auf das Zentrum von San Francisco festgelegt:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Die Antwort enthält jetzt distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

Unternehmen finden, die in Zukunft eröffnen

Das folgende Beispiel zeigt eine Autocomplete (New)-Anfrage für Unternehmen, die in Zukunft in New Meadows, Idaho, USA, eröffnet werden:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

Die Antwort enthält Details zum Ort, aber nicht das Eröffnungsdatum.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

Entfernung fehlt in der Antwort

In bestimmten Fällen fehlt distanceMeters im Antworttext, auch wenn origin in der Anfrage enthalten ist. Dies kann in den folgenden Fällen passieren:

  • distanceMeters ist für route-Vorhersagen nicht enthalten.
  • distanceMeters ist nicht enthalten, wenn der Wert 0 ist. Das ist der Fall, wenn die Vorhersagen weniger als 1 Meter vom angegebenen origin-Standort entfernt sind.

Clientbibliotheken, die versuchen, das Feld distanceMeters aus einem geparsten Objekt zu lesen, geben ein Feld mit dem Wert 0 zurück. Um Nutzer nicht in die Irre zu führen, sollten Sie keine Entfernung von null anzeigen.

Autocomplete (New)-Optimierung

Hier finden Sie Best Practices, damit Sie den Autocomplete-Dienst (New) optimal nutzen können.

Allgemeine Richtlinien:

Best Practices für die Kostenoptimierung

Einfache Kostenoptimierung

Wenn Sie die Kosten für die Nutzung des Autocomplete (New)-Dienstes optimieren möchten, verwenden Sie Feldmasken in Place Details (New)- und Autocomplete (New)-Widgets, damit nur die erforderlichen Datenfelder für Autocomplete (New) zurückgegeben werden.

Erweiterte Kostenoptimierung

Wenn Sie Autocomplete (New) programmatisch implementieren, erhalten Sie Zugriff auf die Preise für die SKU „Autocomplete Request“ und können Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details (New)-Ergebnissen anfordern. Wenn Sie die Kosten pro Anfrage mit der Geocoding API kombinieren, ist das kosteneffizienter als die Verwendung von Kosten pro Sitzung (sitzungsbasiert), sofern die beiden folgenden Bedingungen erfüllt werden:

  • Wenn Sie nur den Breiten- und Längengrad oder die Adresse des vom Nutzer ausgewählten Orts abrufen möchten, erhalten Sie entsprechende Informationen über die Geocoding API, für die weniger Kosten anfallen als bei einem Place Details (New)-Aufruf.
  • Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich maximal 4 entsprechenden Anfragen auswählen, ist der Preis pro Anfrage möglicherweise kosteneffizienter als der Preis pro Sitzung.
Wenn Sie die Autocomplete (New)-Implementierung auswählen möchten, die für Ihre Anwendung am günstigsten ist, suchen Sie in der folgenden Tabelle nach der Zeile, die den Anforderungen Ihrer Anwendung entspricht.
Was in deinem Antrag enthalten sein muss Durchschnittliche Anzahl der Autocomplete (New)-Anfragen, bevor ein Nutzer einen Vorschlag auswählt Empfohlene Implementierung
Place Details, die nicht die Adresse und den Standort betreffen, z. B. den Namen des Ortes, den Unternehmensstatus oder die Öffnungszeiten Beliebig Sitzungsbasierte Autocomplete (Neu) mit Place Details (Neu)
Nur Adresse und Breiten-/Längengrad des ausgewählten Vorschlags Vier oder weniger Anfragebasierte Autocomplete (New) mit der Geocoding API
Nur Adresse und Breiten-/Längengrad des ausgewählten Vorschlags Mehr als vier Sitzungsbasierte Autocomplete (New) für Anwendungen, die nur Adressen verwenden

Wenn Sie Autocomplete (New) in Ihrer Anwendung stark nutzen, kann es kostengünstiger sein, anstelle von Place Details (New) die Geocoding API zu verwenden. Die Effizienz der Autovervollständigung (New) jeder Anwendung hängt davon ab, was die Nutzer eingeben, wo die Anwendung verwendet wird und ob die Best Practices zur Leistungsoptimierung implementiert wurden.

Um die durchschnittliche Anzahl der Anfragen für die Tabelle zu ermitteln, analysieren Sie, wie viele Zeichen Nutzer durchschnittlich eingeben, bevor sie in Ihrer Anwendung einen Autocomplete (New)-Vorschlag auswählen.

Sitzungsbasierte Autocomplete-Anfragen (neu) mit Place Details-Anfragen (neu)

Nutzen Sie das sitzungsbasierte Autocomplete (New) mit Place Details (New).
Da Ihre Anwendung Place Details (New) wie den Ortsnamen, den Geschäftsstatus oder die Öffnungszeiten benötigt, sollte Ihre Implementierung von Autocomplete (New) ein Sitzungstoken verwenden (programmatisch oder in die Widgets für JavaScript, Android oder iOS integriert). Die Abrechnung erfolgt pro Sitzung zuzüglich der entsprechenden Places-SKUs, je nachdem, welche Ortsdatenfelder Sie anfordern.1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android oder iOS integriert. Das umfasst sowohl Autocomplete (New)-Anfragen als auch die Place Details (New)-Anfrage für die ausgewählte Vervollständigung. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Autocomplete (New)-Datenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Place Details (New) für die ausgewählte Vervollständigung anfordern:

  1. Die Orts-ID aus der Autocomplete (New)-Antwort
  2. Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
  3. Den fields-Parameter, mit dem die erforderlichen Datenfelder für Autocomplete (New) angegeben werden

Automatische Vervollständigung (New) pro Anfrage mit der Geocoding API

Implementieren Sie Autocomplete (New) programmatisch ohne Sitzungstokens und rufen Sie die Geocoding API für die ausgewählte Ortsvervollständigung auf.
Über die Geocoding API erhalten Sie Adressen und Breiten-/Längenkoordinaten. Vier Autocomplete-Anfragen plus ein Geocoding API-Aufruf für die ausgewählte Ortsvervollständigung kosten weniger als eine Sitzung mit Autocomplete (New).1

Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vervollständigungen.

Sitzungsbasierte automatische Vervollständigung (neu) für Anwendungen, die nur Adressen verwenden

Nutzen Sie das sitzungsbasierte Autocomplete (New) mit Place Details (New).
Da die durchschnittliche Anzahl der Anfragen, die Sie voraussichtlich stellen, bevor ein Nutzer eine Autocomplete (New)-Vervollständigung auswählt, die Kosten für die Preisgestaltung pro Sitzung übersteigt, sollte Ihre Implementierung von Autocomplete (New) ein Sitzungstoken sowohl für die Autocomplete (New)-Anfragen als auch für die zugehörige Place Details (New)-Anfrage verwenden. pro Sitzung. 1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android oder iOS integriert. Das umfasst sowohl Autocomplete (New)-Anfragen als auch die Place Details (New)-Anfrage für die ausgewählte Vervollständigung. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Felder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Place Details (New) für die ausgewählte Vervollständigung anfordern:

  1. Die Orts-ID aus der Autocomplete (New)-Antwort
  2. Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
  3. Den fields-Parameter, mit dem Felder wie „Adresse“ oder „Geometrie“ angegeben werden

Autocomplete (New)-Anfragen verzögern
Sie können Autocomplete (New)-Anfragen verzögern, bis der Nutzer die ersten 3 oder 4 Zeichen eingegeben hat, damit weniger Anfragen über die Anwendung gestellt werden. Wenn Sie beispielsweise Autocomplete (New)-Anfragen für jedes Zeichen stellen, nachdem der Nutzer das dritte Zeichen eingegeben hat, und der Nutzer sieben Zeichen eingibt und dann eine Vervollständigung auswählt, für die Sie eine Geocoding API-Anfrage stellen, werden die Gesamtkosten für 4 Autocomplete (New)-Anfragen mit Preis pro Anfrage und die Geocoding-Anfrage berechnet.1

Wenn sich durch das Verzögern von Anfragen Ihre durchschnittliche Anzahl programmatischer Anfragen auf unter 4 senken lässt, empfehlen wir, die Anleitung für eine leistungsstarke Autocomplete (New)-Funktion mit Geocoding API-Implementierung zu beachten. Das Verzögern von Anfragen wird vom Nutzer, der evtl. bei jedem eingegebenen Zeichen mit Vorschlägen rechnet, möglicherweise als Latenz wahrgenommen.

Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vervollständigungen.


  1. Informationen zu den Kosten finden Sie in den Preislisten für die Google Maps Platform.

Best Practices für die Leistung

Im Folgenden finden Sie Tipps zum Optimieren der Autocomplete (New)-Leistung:

  • Binden Sie in Ihre Autocomplete (New)-Implementierung länderspezifische Einschränkungen, eine Standortgewichtung und (bei programmatischen Implementierungen) eine Spracheinstellung ein. Die Spracheinstellung ist bei Widgets nicht erforderlich, weil bei ihnen die Spracheinstellungen aus dem Browser oder vom Mobilgerät des Nutzers übernommen werden.
  • Wenn Autocomplete (New) mit einer Karte kombiniert wird, können Sie den Standort anhand des Darstellungsbereichs der Karte gewichten.
  • Wenn ein Nutzer keinen der Vorschläge der automatischen Vervollständigung (New) auswählt, was in der Regel geschieht, wenn es sich bei keinem Vorschlag um die gewünschte Adresse handelt, können Sie anhand der ursprünglichen Nutzereingabe versuchen, relevantere Ergebnisse zu erhalten:
    • Wenn der Nutzer voraussichtlich nur Adressinformationen eingibt, können Sie die ursprüngliche Nutzereingabe bei einem Aufruf der Geocoding API noch einmal verwenden.
    • Wenn Sie davon ausgehen, dass der Nutzer Abfragen für einen bestimmten Ort mithilfe von Name oder Adresse eingibt, verwenden Sie eine „Place Details (New)“-Anfrage. Wenn nur in einer bestimmten Region Ergebnisse erwartet werden, nutzen Sie die Standortgewichtung.
    Bei folgenden Szenarien empfehlen wir, ein Fallback auf die Geocoding API zu nutzen:
    • Nutzer, die Adressen von Untereinheiten eingeben, z. B. Adressen für bestimmte Einheiten oder Wohnungen in einem Gebäude. So wird bei der tschechischen Adresse „Stroupežnického 3191/17, Praha“ z. B. eine teilweise Vervollständigung in Autocomplete (New) ausgegeben.
    • Wenn Nutzer Adressen mit Präfixen für Straßenabschnitte eingeben, z. B. „23-30 29th St, Queens“ in New York City oder „47-380 Kamehameha Hwy, Kaneohe“ auf der Insel Kauai in Hawaii

Standortgewichtung

Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Bereichs gewichten. Dadurch werden von Autocomplete (New) vorzugsweise Ergebnisse für Orte angezeigt, die sich innerhalb des definierten Bereichs befinden. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter includedRegionCodes können Sie die Ergebnisse so filtern, dass nur Orte in einem bestimmten Land angezeigt werden.

Standorteinschränkung

Sie können die Ergebnisse auf einen bestimmten Bereich beschränken, indem Sie den Parameter locationRestriction übergeben.

Sie können die Ergebnisse auch auf die Region beschränken, die durch die Parameter location und radius definiert ist, indem Sie den Parameter locationRestriction hinzufügen. Dadurch wird Autocomplete (New) angewiesen, nur Ergebnisse innerhalb dieser Region zurückzugeben.

Testen!

Mit dem APIs Explorer können Sie Beispielanfragen erstellen, um sich mit der API und den API-Optionen vertraut zu machen.

  1. Wählen Sie rechts auf der Seite das API-Symbol api aus.

  2. Bearbeiten Sie optional die Anfrageparameter.

  3. Wählen Sie den Button Ausführen aus. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.

  4. Wählen Sie im APIs Explorer-Bereich das Vollbildsymbol fullscreen aus, um das APIs Explorer-Fenster zu maximieren.