Automatische Vervollständigung (neu)

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

Der Dienst „Autocomplete (New)“ kann einen Abgleich mit vollständigen Wörtern und Teilstrings der Eingabe durchführen, um Ortsnamen, Adressen und Plus Codes aufzulösen. Anwendungen können daher Abfragen senden, während der Nutzer tippt, um spontan Orts- und Abfragevorhersagen 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 Textstring und Suchbereich. Vorschläge für Orte werden standardmäßig zurückgegeben.
  • Abfragevorhersagen: Abfragestrings, die mit dem Eingabetextstring und dem Suchbereich übereinstimmen. Abfragevorhersagen werden standardmäßig nicht 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 teilweise Nutzereingabe "Sicilian piz" enthält, wobei der Suchbereich auf San Francisco, CA beschränkt ist. 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 bei der Auswahl des gewünschten Ortes zu helfen. Sie können eine Place Details (New)-Anfrage stellen, um weitere Informationen zu zurückgegebenen Ortsvorschlägen zu erhalten.

Die Antwort kann auch eine Liste von Abfragevorhersagen enthalten, die dem Suchstring und dem Suchbereich entsprechen, z. B. „Sizilianische Pizza & 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 API Explorer können Sie Live-Anfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:

Testen!

Autocomplete-Anfragen (neu)

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

Informationen zur Antwort

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

  • Das Array suggestions enthält alle vorgeschlagenen Orte und Suchanfragen in der Reihenfolge ihrer wahrgenommenen Relevanz. Jeder Ort wird durch das Feld placePrediction und jede Abfrage durch das Feld queryPrediction dargestellt.
  • Das Feld placePrediction enthält detaillierte Informationen zu einem einzelnen Ortsvorschlag, einschließlich der Orts-ID und Textbeschreibung.
  • Das Feld queryPrediction enthält detaillierte Informationen zu einer einzelnen Abfragevorhersage.

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 sortiert die Ergebnisse nach ihrer erkannten Relevanz.

Optionale Parameter

  • includedPrimaryTypes

    Ein Ort kann nur einen einzigen primären Typ aus den Typen haben, die in Tabelle A oder Tabelle B aufgeführt sind. 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. Beschränken Sie die Ergebnisse auf einen bestimmten primären Typ oder primäre Typen. Übergeben Sie dazu den Parameter includedPrimaryTypes.

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

    Dieser Parameter kann stattdessen (regions) oder (cities) enthalten. Mit der Typsammlung (regions) können Sie nach Gebieten oder Unterteilungen wie Stadtteilen und Postleitzahlen filtern. Der Sammlungstyp (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.
    • Jeder Typ wird zusätzlich zu (cities) oder (regions) angegeben.
    • Alle nicht erkannten Typen sind angegeben.
  • includeQueryPredictions

    Bei true enthält die Antwort sowohl Orts- als auch Abfragevorhersagen. Der Standardwert ist false, d. h. die Antwort enthält nur Vorschläge für Orte.

  • includedRegionCodes

    Es werden nur Ergebnisse aus der Liste der angegebenen Regionen berücksichtigt, die als Array aus bis zu 15 zweistelligen ccTLD-Werten („Top-Level-Domain“) angegeben werden. Wenn diese Angabe weggelassen 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 input verwendet.

  • languageCode

    Die bevorzugte Sprache, in der Ergebnisse zurückgegeben werden sollen. Die Ergebnisse können in gemischten Sprachen vorliegen, wenn die in input verwendete Sprache sich von dem durch languageCode angegebenen Wert unterscheidet oder wenn der zurückgegebene Ort keine Übersetzung von der lokalen Sprache in languageCode hat.

    • Sie müssen die IETF-BCP-47-Sprachcodes verwenden, um die bevorzugte Sprache anzugeben.
    • Ist languageCode nicht angegeben, verwendet die API den im Accept-Language-Header angegebenen Wert. Wenn weder das eine noch das andere 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 Ergebnisse, die von der API zurückgegeben werden, sowie die Reihenfolge, in der sie zurückgegeben werden. Dies wirkt sich auch auf die Korrektur von Rechtschreibfehlern durch die API aus.
    • Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für die Bevölkerung vor Ort lesbar ist und gleichzeitig die Nutzereingabe wiedergibt. Ortsvorschläge werden je nach Nutzereingabe bei der jeweiligen Anfrage unterschiedlich formatiert.
      • Übereinstimmende Begriffe im input-Parameter werden zuerst ausgewählt. Dabei werden Namen verwendet, die der durch den languageCode-Parameter angegebenen Spracheinstellung (sofern verfügbar) entsprechen. Andernfalls werden Namen verwendet, die am besten zur Nutzereingabe passen.
      • Adressen werden erst dann in der lokalen Sprache formatiert, wenn der Nutzer sie nach Möglichkeit in einem Skript lesen kann, nachdem übereinstimmende Begriffe ausgewählt wurden, die mit den Begriffen im input-Parameter übereinstimmen.
      • Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem übereinstimmende Begriffe ausgewählt wurden, die mit den Begriffen im Parameter input übereinstimmen. Wenn ein Name nicht in der bevorzugten Sprache verfügbar ist, verwendet die API die höchste Übereinstimmung.
  • locationBias oder locationRestriction

    Sie können locationBias oder locationRestriction angeben, aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sich locationRestriction als die Angabe der Region vor, in der sich die Ergebnisse befinden müssen, und locationBias als die Angabe der Region, in der sich die Ergebnisse in der Nähe, aber außerhalb dieses Bereichs befinden müssen.

    • locationBias

      Gibt einen zu durchsuchenden Bereich an. Dieser Standort dient als Verzerrung, das heißt, dass Ergebnisse rund um den angegebenen Standort zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs.

    • locationRestriction

      Gibt einen zu durchsuchenden Bereich an. 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 den Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 (jeweils 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 für Breiten- und Längengrad, der als zwei diagonal gegenüberliegende low- und Höchstwerte dargestellt wird. Ein Darstellungsbereich wird als geschlossener Bereich betrachtet, d. h. er enthält seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen zwischen -180 und 180 Grad (jeweils einschließlich):

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

      Dieser Darstellungsbereich umfasst beispielsweise New York City:

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

    Der Startpunkt, von dem aus die Luftentfernung zum Ziel berechnet werden soll (zurückgegeben als distanceMeters). Wenn dieser Wert weggelassen wird, wird keine Luftlinie zurückgegeben. Diese müssen in Form von 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. Die ccTLD des Vereinigten Königreichs lautet beispielsweise „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ lautet (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äß anwendbarem Recht auf Ergebnisse auswirken.

  • sessionToken

    Sitzungstokens sind vom Nutzer generierte Strings, die Aufrufe der automatischen Vervollständigung (New) als „Sitzungen“ erfassen. Die Funktion „Autocomplete (neu)“ verwendet Sitzungstokens, um die Abfrage- und Auswahlphasen einer automatischen Vervollständigung durch den Nutzer zu Abrechnungszwecken in einer separaten Sitzung zu gruppieren. Weitere Informationen finden Sie unter Sitzungstokens.

Beispiele für die automatische Vervollständigung (neu)

„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, um die Ergebnisse zu gewichten. Sie können optional locationRestriction oder locationBias, aber nicht beides verwenden, um einen Bereich anzugeben, in dem gesucht werden soll.

locationRestriction gibt den Bereich 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 beschränken, der in der Mitte 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 innerhalb der angegebenen Gebiete 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 Gewichtung. Das bedeutet, dass Ergebnisse rund um den angegebenen Standort zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs. Im nächsten Beispiel ändern Sie die Anfrage so, dass sie locationBias verwendet:

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 viele weitere Elemente, einschließlich Ergebnissen 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"
        ]
      }
    },
    ...
  ]
}

EingeschlossenePrimärtypen 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, um in die Antwort aufgenommen zu werden.

Im folgenden Beispiel geben Sie als input-String „Soccer“ an und verwenden den Parameter includedPrimaryTypes, um die Ergebnisse auf Orte 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 Elemente eines unerwünschten Typs enthalten, z. B. "athletic_field".

Abfragevorhersagen anfordern

Abfragevorhersagen werden standardmäßig nicht 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 Vorschläge für Orte als auch für Suchanfragen, wie oben unter Informationen zur Antwort gezeigt. Jede Abfragevorhersage enthält das Feld text mit einem empfohlenen Textsuchstring. Sie können eine Text Search (New)-Anfrage stellen, um weitere Informationen zu allen zurückgegebenen Abfragevorhersagen zu erhalten.

Ursprung verwenden

Nehmen Sie in diesem Beispiel origin als Breiten- und Längengrad in die Anfrage auf. Wenn Sie origin angeben, schließt die API das Feld distanceMeters in die Antwort ein, die die Luftentfernung zwischen origin und dem Ziel enthält. In diesem Beispiel wird als Ursprung das Zentrum San Franciscos 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 den API Explorer. aus.
  2. Maximieren Sie optional Standardparameter anzeigen und legen Sie für den Parameter fields die Feldmaske fest.
  3. Bearbeiten Sie optional den Anfragetext.
  4. Klicken Sie auf die Schaltfläche Execute (Ausführen). Wählen Sie im Pop-up-Fenster das Konto aus, mit dem Sie die Anfrage stellen möchten.
  5. Wählen Sie im API Explorer-Bereich das Symbol zum Maximieren Maximieren Sie den API Explorer. aus, um das Fenster „API Explorer“ zu maximieren.