Automatische Vervollständigung (neu)

Plattform auswählen: Android iOS JavaScript Webdienst

Der Dienst „Autocomplete (New)“ ist ein Webdienst, der als Antwort auf eine HTTP-Anfrage Ortsvorhersagen und Abfragevorhersagen zurückgibt. Geben Sie in der Anfrage einen Textsuchstring und geografische Grenzen an, die den Suchbereich steuern.

Der Dienst „Autocomplete (New)“ sucht nach vollständigen Wörtern und Teilstrings der Eingabe und kann so Ortsnamen, Adressen und Plus Codes auflösen. Anwendungen können Abfragen senden, während der Nutzer tippt, um spontan Vorschläge für Orte und Abfragen bereitzustellen.

Die Antwort der Autocomplete (New) API kann zwei Arten von Vorhersagen enthalten:

  • Vervollständigungen von Orten: Orte wie Unternehmen, Adressen und POIs, basierend auf dem angegebenen Eingabetextstring und dem Suchbereich. Vervollständigungen von Orten werden standardmäßig zurückgegeben.
  • Vervollständigungen von Suchanfragen: Abfragestrings, die mit dem eingegebenen Textstring und dem Suchbereich übereinstimmen. Vervollständigungen von Suchanfragen werden nicht standardmäßig zurückgegeben. Verwenden Sie den Anfrageparameter includeQueryPredictions, um der Antwort Abfragevorhersagen hinzuzufügen.

Beispiel: Sie rufen die API auf und verwenden als Eingabe einen String, der die Teileingabe des Nutzers "Sicilian piz" enthält, wobei der Suchbereich auf San Francisco beschränkt ist. Die Antwort enthält dann eine Liste von Ortsvorschlägen, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. das Restaurant mit dem Namen „Sicilian Pizza Kitchen“, sowie Details zum Ort.

Die zurückgegebenen Ortsvorschläge sollen dem Nutzer angezeigt werden, um ihn bei der Auswahl des gewünschten Ortes zu unterstützen. Mit der Anfrage Place Details (New) können Sie weitere Informationen zu zurückgegebenen Orten erhalten.

Die Antwort kann auch eine Liste von Vervollständigungen für die Suchanfrage enthalten, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. "Sizilianische Pizza & Pasta". Jede Vorhersageanfrage 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 API Explorer können Sie Live-Anfragen stellen, damit Sie sich mit der API und den API-Optionen vertraut machen können:

Testen!

Autocomplete (New)-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 den 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

Informationen zur Antwort

„Autocomplete (New)“ gibt ein JSON-Objekt als Antwort zurück. In der Antwort:

  • Das Array suggestions enthält alle vorhergesagten Orte und Suchanfragen der Reihenfolge nach erkannter Relevanz. Jeder Ort wird durch ein placePrediction-Feld und jede Abfrage durch ein queryPrediction-Feld dargestellt.
  • Das Feld placePrediction enthält detaillierte Informationen zu einer einzelnen Vervollständigung eines Orts, einschließlich der Orts-ID und einer Textbeschreibung.
  • Das Feld queryPrediction enthält detaillierte Informationen zu einer einzelnen Vorhersage einer Abfrage.

Das vollständige JSON-Objekt hat das folgende 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

    Die Textzeichenfolge, nach der gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Der Dienst „Autocomplete (New)“ gibt mögliche Übereinstimmungen basierend auf diesem String zurück und ordnet die Ergebnisse nach erkannter Relevanz.

Optionale Parameter

  • includedPrimaryTypes

    Ein Ort kann nur einen einzelnen 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 Wert des primären Typs, der dem Ort zugeordnet ist. Schränken Sie die Ergebnisse auf einen bestimmten primären Typ oder primäre Typen ein, indem Sie den Parameter includedPrimaryTypes übergeben.

    Verwenden Sie diesen Parameter, um bis zu fünf Typwerte aus Tabelle A oder Tabelle B anzugeben. Ein Ort muss mit einem der angegebenen Werte des primären Typs übereinstimmen, um in die Antwort aufgenommen zu werden.

    Dieser Parameter kann stattdessen auch (regions) oder (cities) enthalten. Die Sammlungsfilter des Typs (regions) filtern für Gebiete oder Abteilungen wie Stadtteile und Postleitzahlen. Die Typensammlung (cities) filtert nach Orten, die Google als Stadt identifiziert.

    In folgenden Fällen wird die Anfrage mit dem Fehler INVALID_REQUEST abgelehnt:

    • Es sind mehr als fünf Typen angegeben.
    • Zusätzlich zu (cities) oder (regions) wird jeder Typ angegeben.
    • Alle nicht erkannten Typen wurden angegeben.
  • includeQueryPredictions

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

  • includedRegionCodes

    Schließt nur Ergebnisse aus der Liste der angegebenen Regionen ein, angegeben als Array mit bis zu 15 zweistelligen ccTLD-Werten ("top-level domain"). Wenn keine Angabe gemacht wird, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie beispielsweise 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 Vorhersagen 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 gemischten Sprachen vorliegen, wenn sich die in input verwendete Sprache von dem in languageCode angegebenen Wert unterscheidet oder der zurückgegebene Ort keine Übersetzung von der lokalen Sprache in languageCode hat.

    • Zur Angabe der bevorzugten Sprache musst du IETF BCP-47-Sprachcodes verwenden.
    • Wenn languageCode nicht angegeben ist, verwendet die API den im Accept-Language-Header angegebenen Wert. Wenn keins von beiden angegeben ist, wird der Standardwert 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 Ergebnisse, die von der API zurückgegeben werden, und auf die Reihenfolge, in der sie zurückgegeben werden. Dies beeinträchtigt auch die Fähigkeit der API, Rechtschreibfehler zu korrigieren.
    • Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für die örtliche Bevölkerung lesbar ist und gleichzeitig die Nutzereingabe widerspiegelt. Vervollständigungen von Orten werden je nach Nutzereingabe in den einzelnen Anfragen unterschiedlich formatiert.
      • Übereinstimmende Begriffe im input-Parameter werden zuerst ausgewählt. Dabei werden Namen verwendet, die der durch den languageCode-Parameter angegebenen Spracheinstellung entsprechen, sofern verfügbar. Andernfalls werden die Namen verwendet, die am besten mit der Nutzereingabe übereinstimmen.
      • Adressen werden in der Landessprache und nach Möglichkeit in einem für den Nutzer lesbaren Script formatiert, wenn übereinstimmende Begriffe mit denen im input-Parameter übereinstimmen.
      • Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem übereinstimmende Begriffe mit den Begriffen im input-Parameter übereinstimmen. Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die am besten passende Übereinstimmung.
  • „locationBias“ oder „locationRestriction“

    Sie können locationBias oder locationRestriction angeben, aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sich locationRestriction vor, um die Region anzugeben, in der sich die Ergebnisse befinden müssen, und locationBias die Region, in der sich die Ergebnisse befinden müssen, aber außerhalb des Bereichs sein können.

    • locationBias

      Gibt das Gebiet an, in dem gesucht werden soll. Dieser Standort dient als Verzerrung, d. h., Ergebnisse um den angegebenen Standort herum können zurückgegeben werden, auch solche außerhalb des angegebenen Bereichs.

    • locationRestriction

      Gibt das Gebiet an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.

    Geben Sie den Bereich 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 (einschließlich) liegen. Der Standardwert ist 0,0. Für locationRestriction müssen Sie den Radius auf einen Wert größer als 0,0 festlegen. Andernfalls gibt die Anfrage keine Ergebnisse zurück.

      Beispiel:

      "locationBias": {
        "circle": {
          "center": {
            "latitude": 37.7937,
            "longitude": -122.3965
          },
          "radius": 500.0
        }
      }
    • Ein Rechteck ist ein Darstellungsbereich mit Breiten- und Längengrad, der als zwei diagonal gegenüberliegende low und hohe Punkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossener Bereich, d. h. er umfasst seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad und die Längengradgrenzen zwischen -180 und 180 Grad liegen.

      • Wenn low = high, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude ist, wird der Längengradbereich umgekehrt (der Darstellungsbereich kreuzt die 180-Grad-Längenlinie).
      • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad ist, enthält 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 werden und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

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

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

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

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

    Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger ccTLD-Wert ("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) und der ISO 3166-1-Code „gb“ (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“).

    Wenn Sie einen ungültigen Regionscode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück. Der Parameter kann sich gemäß geltendem Recht auf Ergebnisse auswirken.

  • sessionToken

    Sitzungstokens sind vom Nutzer erstellte Strings, die Aufrufe der automatischen Vervollständigung (Neu) als „Sitzungen“ erfassen. „Autocomplete (New)“ verwendet Sitzungstokens, um die Abfrage- und Auswahlphasen einer Nutzersuche mit automatischer Vervollständigung zu Abrechnungszwecken in einer separaten Sitzung zu gruppieren. Weitere Informationen finden Sie unter Sitzungstokens.

Beispiele für Autocomplete (New)

„locationRestriction“ und „locationBias“ verwenden

Die API verwendet standardmäßig die IP-Gewichtung, um den Suchbereich zu steuern. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts zur Gewichtung der Ergebnisse. Sie können optional locationRestriction oder locationBias verwenden, aber nicht beides, um einen Bereich anzugeben, in dem gesucht werden soll.

locationRestriction gibt das Gebiet an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel verwenden Sie locationRestriction, um die Anfrage auf einen Kreis mit einem Radius von 5.000 Metern zu begrenzen, der auf San Francisco liegt:

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

Bei locationBias dient der Standort als Verzerrung, sodass Ergebnisse um den angegebenen Ort herum zurückgegeben werden können, auch solche außerhalb des angegebenen Bereichs. Im nächsten Beispiel ändern Sie die Anfrage in locationBias:

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, darunter auch Ergebnisse außerhalb des Umkreises 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"
        ]
      }
    },
    ...
  ]
}

„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 Werte des primären Typs übereinstimmen, um in die Antwort aufgenommen zu werden.

Im folgenden Beispiel geben Sie einen input-String von "Soccer" an und verwenden den Parameter includedPrimaryTypes, um Ergebnisse auf Einrichtungen des Typs "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 Ergebnisse eines unerwünschten Typs enthalten, z. B. "athletic_field".

Abfragevorhersagen anfordern

Vervollständigungen von Suchanfragen werden nicht standardmäßig zurückgegeben. Verwenden Sie den Anfrageparameter includeQueryPredictions, um der Antwort Abfragevorhersagen 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 Abfragevervollständigungen, wie oben unter Informationen zur Antwort dargestellt. Jede Vorhersageanfrage enthält das Feld text mit einem empfohlenen Textsuchstring. Mit einer Text Search (New)-Anfrage können Sie weitere Informationen zu den zurückgegebenen Abfragevorhersagen abrufen.

Ursprung verwenden

Fügen Sie in diesem Beispiel origin als Breiten- und Längengrad in die Anfrage ein. Wenn Sie origin angeben, schließt die API das Feld distanceMeters in die Antwort ein, das die direkte Entfernung von origin zum Ziel enthält. In diesem Beispiel wird als Startpunkt 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
      }
    }
  ]
}

Jetzt testen

Mit dem API 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 Maximieren Sie API Explorer. aus.
  2. Erweitern Sie optional Standardparameter anzeigen und legen Sie den Parameter fields auf die Feldmaske fest.
  3. Optional können Sie den Anfragetext bearbeiten.
  4. Klicken Sie auf die Schaltfläche Execute (Ausführen). Wählen Sie im Pop-up-Fenster das Konto aus, das Sie für die Anfrage verwenden möchten.
  5. Klicken Sie im Bereich „API Explorer“ auf das Symbol zum Maximieren (Maximieren Sie API Explorer.), um das API Explorer-Fenster zu maximieren.