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.

Mit Autocomplete (New) können vollständige Wörter und Teilstrings der Eingabe abgeglichen werden, 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 Autocomplete (New) kann zwei Arten von Vorhersagen enthalten:

  • Ortsvorhersagen: Orte wie Unternehmen, Adressen und POIs, die auf dem angegebenen Eingabetextstring und Suchgebiet basieren. Ortsvorschläge werden standardmäßig zurückgegeben.
  • Vorhersagen für Suchanfragen: Suchanfragestrings, die mit dem eingegebenen Textstring und dem Suchbereich übereinstimmen. Abfragevorhersagen werden standardmäßig nicht 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, der eine teilweise Nutzereingabe enthält, nämlich „Sicilian piz“, wobei der Suchbereich auf San Francisco, CA, beschränkt ist. Die Antwort enthält dann eine Liste von Ortsvorhersagen, die dem Suchstring und dem Suchgebiet entsprechen, z. B. das Restaurant „Sicilian Pizza Kitchen“ mit Details zum Ort.

Die zurückgegebenen Ortsvorhersagen 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 von Abfragevorhersagen enthalten, die dem Suchstring und dem Suchgebiet entsprechen, z. B. „Sicilian Pizza & Pasta“. Jede Vorhersage für eine Anfrage 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 (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 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 für die Suche (vollständige Wörter, Teilstrings, Ortsnamen, Adressen, Plus Codes).

FieldMask (HTTP-Header)

Durch Kommas getrennte Liste, die angibt, 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) berücksichtigt. Die Standardeinstellung ist "false".

includeQueryPredictions

Bei „true“ werden sowohl Orts- als auch Suchvorhersagen 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

Nullbasiertes Unicode-Zeichen-Offset der Cursorposition im Eingabestring, das Vorhersagen 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, in dem Suchergebnisse bevorzugt werden. 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

Der Startpunkt (Breiten- und Längengrad), der zum Berechnen der Luftlinie (distanceMeters) zu den vorhergesagten Zielorten 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

Über die Antwort

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

  • Das Array suggestions enthält alle vorhergesagten Orte und Anfragen in der Reihenfolge ihrer wahrgenommenen Relevanz. Jeder Ort wird durch ein placePrediction-Feld und jede Anfrage durch ein queryPrediction-Feld dargestellt.
  • Das Feld placePrediction enthält detaillierte Informationen zu einer einzelnen Ortsvorhersage, einschließlich der Orts-ID und einer Textbeschreibung.
  • Ein queryPrediction-Feld enthält detaillierte Informationen zu einer einzelnen Vorhersage für eine Anfrage.

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. Über den Dienst „Autocomplete (New)“ werden mögliche Übereinstimmungen basierend auf dem String zurückgegeben, die nach erkannter Relevanz sortiert werden.

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 des Vorschlags abrufen.

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

    Verwenden Sie *, um alle Felder abzurufen.

      X-Goog-FieldMask: *

  • includedPrimaryTypes

    Ein Ort kann nur einen primären Typ haben, der in Tabelle A oder Tabelle B aufgeführt ist. 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 einem der angegebenen primären Typwerte entsprechen, damit er in die Antwort aufgenommen wird.

    Dieser Parameter kann stattdessen auch (regions) oder (cities) enthalten. Mit Sammlungsfiltern vom Typ (regions) werden Bereiche oder Unterteilungen wie Stadtviertel und Postleitzahlen gefiltert. Die Typensammlung (cities) filtert nach Orten, 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.
    • Ein beliebiger Typ wird zusätzlich zu (cities) oder (regions) 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 beliefern, aber keinen physischen 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 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. Diese werden als Array mit bis zu 15 zweistelligen ccTLD-Werten (Top-Level-Domain) angegeben. Wenn Sie das Flag weglassen, 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 Schnittmengenbereich der beiden Einstellungen.

  • inputOffset

    Das nullbasierte Unicode-Zeichen-Offset, das die Cursorposition in input angibt. Die Cursorposition kann sich darauf auswirken, 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 von der lokalen Sprache 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 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 wirkt sich auch auf die Fähigkeit der API aus, Rechtschreibfehler zu korrigieren.
    • Die API versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für die lokale Bevölkerung lesbar ist und gleichzeitig die Nutzereingabe widerspiegelt. Ortsvorhersagen werden je nach Nutzereingabe in der jeweiligen Anfrage unterschiedlich formatiert.
      • Übereinstimmende Begriffe im Parameter input werden zuerst ausgewählt. Dabei werden Namen verwendet, die mit der durch den Parameter languageCode angegebenen Spracheinstellung übereinstimmen, sofern verfügbar. Andernfalls werden Namen verwendet, die am besten mit der Nutzereingabe übereinstimmen.
      • Straßenadressen werden in der lokalen Sprache und, wenn möglich, in einem für den Nutzer lesbaren Schriftsystem formatiert. Dies erfolgt erst, nachdem passende 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, wird die nächstgelegene Übereinstimmung verwendet.

  • locationBias oder locationRestriction

    Sie können locationBias oder locationRestriction angeben, aber nicht beide, 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 sich auch befinden 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 Ergebnisse 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 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 Darstellungsbereich, der durch zwei diagonal gegenüberliegende low- und Hochpunkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossener Bereich, d. h., er umfasst auch seine Grenze. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen (einschließlich), und die Grenzen für den Längengrad müssen zwischen -180 und 180 Grad liegen (einschließlich):

      • 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 Rechteck darf nicht leer sein. Ein leerer Viewport 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 Koordinaten für Breiten- und Längengrad angegeben werden:

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

  • regionCode

    Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als zweistelliger Ländercode der Top-Level-Domain (ccTLD). Die meisten ccTLD-Codes sind mit den ISO 3166-1-Codes identisch. 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 von Großbritannien und Nordirland“).

    Vorschläge sind auch durch Regionscodes beeinflusst. Google empfiehlt, regionCode entsprechend der regionalen Präferenz des Nutzers festzulegen.

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

  • sessionToken

    Sitzungstokens sind von Nutzern generierte Strings, mit denen Autocomplete (New)-Aufrufe als „Sitzungen“ erfasst werden. In 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 auswählen, um Ergebnisse zu beeinflussen

Parameter für die automatische Vervollständigung (neu) können Suchergebnisse unterschiedlich beeinflussen. Die folgende Tabelle enthält Empfehlungen zur Verwendung von Parametern basierend auf dem gewünschten Ergebnis.
Parameter Verwendungsempfehlung
regionCode Entsprechend der regionalen Präferenz des Nutzers festlegen.
includedRegionCodes Wird festgelegt, um die Ergebnisse auf die Liste der angegebenen Regionen zu beschränken.
locationBias Wird verwendet, 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 Wird verwendet, wenn eine Luftlinie zu jeder Vorhersage angegeben werden soll.

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 zu beschränken, der auf San Francisco zentriert ist:

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

Suchergebnisse mit „locationBias“ auf einen Bereich ausrichten

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

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 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": [
            "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 einem der angegebenen primären Typwerte entsprechen, 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 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 Einrichtungen eines Typs enthalten, den Sie nicht möchten, z. B. "athletic_field".

Vorhersagen für Anfragen anfordern

Abfragevorhersagen werden standardmäßig nicht 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 suggestions-Array 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 Suchvorhersagen zu erhalten.

Ursprung verwenden

In diesem Beispiel müssen Sie origin als Breiten- und Längenkoordinaten in die Anfrage aufnehmen. Wenn Sie origin angeben, 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
      }
    }
  ]
}

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 nicht in den route-Vorhersagen enthalten.
  • distanceMeters wird nicht berücksichtigt, wenn der Wert 0 ist. Das ist bei Vorhersagen der Fall, die weniger als 1 Meter von der angegebenen origin-Position 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 ihnen keine Distanz von null angezeigt werden.

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 die Schaltfläche Ausführen. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.

  4. Wählen Sie im Bereich „APIs Explorer“ das Symbol für den Vollbildmodus fullscreen aus, um das APIs Explorer-Fenster zu maximieren.