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 Ortsvorschläge und Vorschläge für Suchanfragen als Reaktion auf eine HTTP-Anfrage zurückgibt. Geben Sie in der Anfrage einen Textsuchstring und geografische Grenzen an, um den Suchbereich zu steuern.

Place 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:

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

Sie rufen beispielsweise „Autocomplete (New)“ auf und verwenden als Eingabe einen String mit einer teilweisen Nutzereingabe, „Sicilian piz“, wobei der Suchbereich auf San Francisco, CA, beschränkt ist. Die Antwort enthält dann eine Liste mit Ortsvorhersagen, die dem Suchstring und dem Suchgebiet entsprechen, z. B. das Restaurant „Sicilian Pizza Kitchen“ mit Details zum Ort.

Die zurückgegebenen Ortsprognosen sind dafür vorgesehen, dem Nutzer angezeigt zu werden, um ihm bei der Auswahl des gewünschten Orts zu helfen. Sie können eine Place Details (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen Ortsvorhersagen zu erhalten.

Die Antwort kann auch eine Liste mit Suchvorschlägen enthalten, die dem Suchstring und dem Suchbereich entsprechen, z. B. „Sizilianische Pizza und Pasta“. Jede Abfragevorhersage in der Antwort enthält das Feld text mit einem empfohlenen Textsuchstring. 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 (neu)-Anfragen

Eine Autocomplete (New)-Anfrage ist eine HTTP-POST-Anfrage an eine URL in folgendem 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)

Eine 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

Falls zutreffend, umfasst dies Unternehmen ohne physischen Standort (Unternehmen ohne festen Standort in einem Einzugsgebiet). Die Standardeinstellung ist "false".

includeQueryPredictions

Wenn „true“, werden sowohl Orts- als auch Suchanfragen-Vervollständigungen 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

Der nullbasierte Unicode-Zeichen-Offset der Cursorposition im Eingabestring, der sich auf Vorhersagen auswirkt. Die Standardeinstellung ist die Eingabelänge.

languageCode

Bevorzugte Sprache (IETF BCP-47-Code) für Ergebnisse. Standardmäßig wird der Accept-Language-Header oder „en“ verwendet.

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, in dem die Suchergebnisse eingeschränkt werden sollen. Ergebnisse außerhalb dieses Bereichs werden ausgeschlossen. Kann nicht mit „locationBias“ verwendet werden.

origin

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

regionCode

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

sessionToken

Nutzergenerierter 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 suggestions-Array enthält alle vorhergesagten Orte und Anfragen in der Reihenfolge ihrer wahrgenommenen 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 Ortsvorhersage, einschließlich der Orts-ID und der Textbeschreibung.
    • Um die Nutzereingabe, die im Parameter input angegeben ist, genauer zu berücksichtigen, kann die Textbeschreibung eines Ortsvorschlags 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 Zusammenhang können alternative Namen für einige Orte in einer anderen Sprache als erwartet basierend auf dem languageCode-Parameter angegeben werden, je nachdem, welche Namen besser mit der Nutzereingabe übereinstimmen.
  • Das Feld queryPrediction enthält detaillierte Informationen zu einer einzelnen Vorhersage für eine Anfrage.

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 dem String zurück und sortiert die Ergebnisse nach erkannter 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 Maske für das Antwortfeld 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: suggestions.placePrediction.text.text und suggestions.queryPrediction.text.text der Empfehlung abrufen.

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

    Verwenden Sie *, um alle Felder abzurufen.

      X-Goog-FieldMask: *

  • includeFutureOpeningBusinesses

    Falls 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 kann 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 einem der angegebenen primären Typwerte entsprechen, damit er in die Antwort aufgenommen wird.

    Dieser Parameter kann stattdessen auch (regions) oder (cities) enthalten. Der Typ (regions) filtert nach Gebieten oder Bereichen wie Stadtteilen und Postleitzahlen. Mit der Typensammlung (cities) werden Orte herausgefiltert, 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.
    • Es wurden unbekannte Typen angegeben.

  • includePureServiceAreaBusinesses

    Wenn der Wert auf true festgelegt ist, enthält die Antwort Unternehmen, die Kunden vor Ort besuchen oder einen Lieferservice haben, aber keinen physischen Standort haben. Wenn der Wert auf false festgelegt ist, werden von der API nur Unternehmen mit einem physischen Standort zurückgegeben.

  • includeQueryPredictions

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

  • includedRegionCodes

    Es werden nur Ergebnisse aus der Liste der angegebenen Regionen berücksichtigt, die als Array mit bis zu 15 zweistelligen ccTLD-Werten (Ländercode der Top-Level-Domain) angegeben werden. Wenn nicht angegeben, werden keine Einschränkungen auf die Antwort angewendet. Beispiel: So beschränken Sie die Regionen 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 Vorschläge zurückgegeben werden. Wenn leer, 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 Accept-Language-Header angegebenen Wert. Wenn keines angegeben ist, ist der Standardwert en. 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 Menge der Ergebnisse, die von der API zurückgegeben werden, und auf die Reihenfolge, in der sie zurückgegeben werden. Dies wirkt sich auch auf die Fähigkeit der API aus, Rechtschreibfehler zu korrigieren.
    • Ortsvorhersagen werden je nach Nutzereingabe in der jeweiligen Anfrage unterschiedlich formatiert.
      • Passende Begriffe im input-Parameter werden zuerst ausgewählt. Dabei werden Namen verwendet, die der mit dem languageCode-Parameter angegebenen Spracheinstellung entsprechen, sofern verfügbar. Andernfalls werden Namen verwendet, die am besten mit der Nutzereingabe übereinstimmen.
      • Ortsnamen können mit alternativen Namen formatiert werden, um Begriffen im Parameter input zu entsprechen. Dazu gehören auch Namen in anderen Sprachen als der Sprache, die durch den Parameter languageCode angegeben wird.
      • Adressen werden in der Landessprache und nach Möglichkeit 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 passende 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 locationBias oder locationRestriction angeben, aber nicht beides, um den Suchbereich zu definieren. 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 derer sie liegen können.

    • 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 wenn sie außerhalb des angegebenen Bereichs liegen.

    • 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 Viewport 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 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 Breiten-/Längengrad-Sichtbereich, der durch zwei diagonal gegenüberliegende low- und Hochpunkte dargestellt wird. Ein Viewport gilt als geschlossener Bereich, d. h., er umfasst auch seine Grenze. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen 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 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.

      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.

      Beispiel: Dieser Viewport umfasst 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 wird (als distanceMeters zurückgegeben). 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 für die ccTLD („Top-Level-Domain“). Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes. 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 Großbritannien und Nordirland“).

    Vorschläge sind auch durch Regionencodes beeinflusst. Google empfiehlt, regionCode entsprechend der regionalen Einstellungen des Nutzers festzulegen.

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

  • sessionToken

    Sitzungstokens sind nutzergenerierte 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 von Ergebnissen auswählen

Parameter für die automatische Vervollständigung (neu) können Suchergebnisse unterschiedlich beeinflussen. In der folgenden Tabelle finden Sie Empfehlungen zur Verwendung von Parametern basierend auf dem gewünschten Ergebnis.
Parameter Nutzungsempfehlung
regionCode Wird entsprechend den regionalen Einstellungen des Nutzers festgelegt.
includedRegionCodes Damit werden die Ergebnisse auf die Liste der angegebenen Regionen beschränkt.
locationBias Verwenden Sie diese Option, wenn Ergebnisse in oder in der Nähe einer Region bevorzugt werden. Definieren Sie die Region gegebenenfalls als den Darstellungsbereich der Karte, die der Nutzer sieht.
locationRestriction Verwenden Sie only, 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 die automatische Vervollständigung (neu)

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 ein rechteckiges Viewport 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 suggestions-Array 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"
          ]
        }
      }
    ]
  }

Gewichtung auf einen Bereich anwenden

Mit locationBias dient der Standort als Gewichtung. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Standorts zurückgegeben werden können, auch wenn sie außerhalb des angegebenen Bereichs liegen. 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, auch 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 ein rechteckiges Viewport auszurichten. 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

Obwohl Suchergebnisse innerhalb des rechteckigen Darstellungsbereichs in der Antwort angezeigt werden, liegen einige Ergebnisse aufgrund der Gewichtung 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 oder 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".

Vorhersagen für Abfrageanfragen

Abfragevorhersagen werden nicht standardmäßig zurückgegeben. Verwenden Sie den Anfrageparameter includeQueryPredictions, um der Antwort Vorhersagen für Suchanfragen 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 Ortsvorschläge als auch Suchvorschläge, wie oben unter Informationen zur Antwort beschrieben. Jede Vorhersage für eine Anfrage enthält das Feld text mit einem empfohlenen Textsuchstring. Sie können eine Text Search (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen Vorhersagen für Suchanfragen zu erhalten.

Ursprung verwenden

In diesem Beispiel sind origin als Breiten- und Längenkoordinaten in der Anfrage enthalten. Wenn Sie origin einfügen, enthält Autocomplete (New) das Feld distanceMeters in der Antwort, das die Luftlinie von origin zum Ziel enthält. 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 Anfrage für die automatische Vervollständigung (neu) für Unternehmen, die in Zukunft in New Meadows, Idaho, 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 wird nicht berücksichtigt, 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, darf Nutzern keine Entfernung von null angezeigt werden.

Autocomplete (New)-Optimierung

In diesem Abschnitt finden Sie Best Practices, damit Sie den Autocomplete (New)-Dienst 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 SKU: Autocomplete Request pricing 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 vier entsprechenden Anfragen auswählen, ist der Preis pro Anfrage möglicherweise kosteneffizienter als der Preis pro Sitzung.
Wenn Sie Hilfe bei der Auswahl der Autocomplete (New)-Implementierung benötigen, klicken Sie auf den Tab, der Ihrer Antwort auf die folgende Frage am ehesten entspricht.

Benötigt Ihre Anwendung weitere Informationen als Adresse und Breiten-/Längengrad des ausgewählten Vorschlags?

Ja, weitere Details sind erforderlich.

Sitzungsbasiertes Autocomplete (New) mit Place Details (New) verwenden
Da für Ihre Anwendung „Place Details (New)“ erforderlich sind, z. B. Ortsname, Unternehmensstatus oder Öffnungszeiten, sollte für die Implementierung von „Autocomplete (New)“ ein Sitzungstoken verwendet werden (programmatisch oder in die JavaScript-, Android- oder iOS-Widgets integriert). pro Sitzung zuzüglich der anwendbaren 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 Datenfelder für Autocomplete (New) angefordert werden.

Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Place Details (neu) 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

Nein, es sind nur Adresse und Standort erforderlich.

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 (Neu) 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 folgende Frage beantworten zu können, analysieren Sie, wie viele Zeichen Nutzer durchschnittlich eingeben, bevor sie in Ihrer Anwendung einen Autocomplete (New)-Vorschlag auswählen.

Wählen Ihre Nutzer durchschnittlich bei 4 oder weniger Anfragen einen Autocomplete (New)-Vorschlag aus?

Ja

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. Wenn 4 Autocomplete-Anfragen ausgeführt werden, fallen Kosten von 0,01132 $ an. Die Gesamtkosten der 4 Anfragen plus die Kosten für einen Geocoding API-Aufruf zum ausgewählten Ortsvorschlag betragen 0,01632 $, also weniger als der Preis pro Sitzung mit automatischer Vervollständigung (neu) von 0,017 $ pro Sitzung.1

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

Nein

Sitzungsbasiertes Autocomplete (New) mit Place Details (New) verwenden
Da die durchschnittliche Anzahl der Anfragen, die Sie voraussichtlich stellen, bevor ein Nutzer einen Autocomplete (New)-Vorschlag auswählt, die Kosten für die Preisgestaltung pro Sitzung übersteigt, sollte für 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 verwendet werden 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 (neu) für den ausgewählten Vorschlag 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“ und „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 nach dem dritten Zeichen ausführen, das der Nutzer eingegeben hat, und der Nutzer sieben Zeichen eingibt und dann einen Vorschlag auswählt, für den Sie eine Geocoding API-Anfrage ausführen, betragen die Gesamtkosten 4 Autocomplete (New)-Anfragen mit Preis pro Anfrage + Geocoding.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-Funktion (Neu) 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 Vorschläge.

  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 (neu) 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

Sie können die Ergebnisse zugunsten eines bestimmten Orts gewichten, indem Sie einen location-Parameter und einen radius-Parameter übergeben. Dadurch wird Autocomplete (New) angewiesen, vorzugsweise Ergebnisse innerhalb des definierten Bereichs anzuzeigen. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter includedRegionCodes können Sie die Ergebnisse filtern, sodass 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 stellen, 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. Klicken Sie auf den Button Ausführen. Wählen Sie im Dialogfeld das Konto aus, mit dem Sie die Anfrage stellen möchten.

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