Automatische Vervollständigung (neu)

„Autocomplete (New)“ ist ein Webdienst, mit dem Vorhersagen und Abfragevorhersagen als Antwort auf eine HTTP-Anfrage. Geben Sie in der Anfrage einen Text Suchzeichenfolge und geografischen Grenzen, die den Suchbereich steuern.

Der Dienst „Autocomplete (New)“ sucht nach vollständigen Wörtern und Teilzeichenfolgen der Eingabe, die Ortsnamen, Adressen und Plus Codes. Anwendungen können daher Suchanfragen während der Nutzereingabe, um spontane Vervollständigungen für Orte und Suchanfragen bereitzustellen.

Die Antwort der Autocomplete (New) API kann zwei Typen enthalten der Vervollständigungen:

• Vervollständigungen von Orten: Orte wie Unternehmen, Adressen und Punkte basierend auf der angegebenen Textzeichenfolge und dem Suchbereich der Eingabe. Vervollständigungen von Orten sind werden standardmäßig zurückgegeben.
• Abfragevorhersagen: Abfragestrings, die mit dem eingegebenen Textstring übereinstimmen Suchbereich. Vervollständigungen von Suchanfragen werden nicht standardmäßig zurückgegeben. Verwenden Sie die Methode includeQueryPredictions-Anfrageparameter, um Abfragevorhersagen zum Antwort.

Beispiel: Sie rufen die API mit einem String auf, der eine teilweise Nutzereingabe enthält, „Sizilianische piz“, wobei der Suchbereich auf San Francisco beschränkt ist. Die Antwort enthält dann ein Liste von Vervollständigungen für Orte, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. Restaurant namens „Sizilianische Pizzaküche“ sowie Details zum jeweiligen Ort.

Die zurückgegebenen Ortsvorschläge sind so konzipiert, dass sie dem Nutzer angezeigt werden, um Ihnen zu helfen. den gewünschten Ort auswählen. Sie können eine Place Details (neu) , um weitere Informationen zu den zurückgegebenen Ortsvorschlägen zu erhalten.

Die Antwort kann auch eine Liste mit Vorhersagen der Suchanfrage enthalten, die dem Suchzeichenfolge und Suchbereich, wie z. B. "Sizilianische Pizza & Pasta“. Jede Vorhersageanfrage in der Antwort das Feld text mit einem empfohlenen Textsuchstring enthält. Verwenden als Eingabe für Textsuche (neu) 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:

Testen!

Autocomplete (New)-Anfragen

Eine Autocomplete (New)-Anfrage ist eine HTTP POST-Anfrage an eine URL in das Formular:

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 Reihe nach basierend auf ihrer wahrgenommenen Relevanz. Jeder Ort wird durch ein placePrediction und jede Abfrage wird dargestellt. durch ein queryPrediction-Feld.
• Das Feld placePrediction enthält detaillierte Informationen zu einem einzelnen Ortsvervollständigung, einschließlich Orts-ID und Textbeschreibung.
• Das Feld queryPrediction enthält detaillierte Informationen zu einem 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 Teilzeichenfolgen an, Ortsnamen, Adressen und Plus Codes. „Autocomplete (New)“-Dienst gibt mögliche Übereinstimmungen basierend auf diesem String zurück und ordnet die Ergebnisse basierend auf ihre wahrgenommene Relevanz.

Optionale Parameter

• includedPrimaryTypes

  Ein Ort kann nur einen einzigen primären Typ aus den Typen haben, die in Tabelle A oder Tabelle B. Beispiel: kann der primäre Typ "mexican_restaurant" oder "steak_house" sein.

  Standardmäßig gibt die API alle Orte basierend auf dem Parameter input zurück, unabhängig davon, des mit dem Ort verknüpften primären Typwerts. Ergebnisse auf einen bestimmten Wert beschränken primären Typ oder primären Typen durch Übergeben des includedPrimaryTypes-Parameters

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

  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. Standardeinstellung Der Wert ist false, was bedeutet, dass die Antwort nur Ortsvorschläge enthält.

• includedRegionCodes

  Nur Ergebnisse aus der Liste der angegebenen Regionen einschließen, angegeben als Array von bis zu 15 ccTLD („Top-Level-Domain“) aus zwei Zeichen bestehen. Wenn keine Angabe gemacht wird, werden keine Einschränkungen auf die Antwort angewendet. Beispiel: zur Beschränkung der 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 das Länge von input.

• languageCode

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

  • Sie müssen IETF verwenden. BCP-47-Sprachcodes zur Angabe der bevorzugten Sprache.
  • Ist languageCode nicht angegeben, verwendet die API den Wert, der in der Accept-Language-Header. Wenn keins von beiden angegeben ist, wird der Standardwert en Wenn Sie einen ungültigen Sprachcode angeben, gibt die API eine INVALID_ARGUMENT Fehler.
  • Die bevorzugte Sprache hat einen geringen Einfluss auf die Suchergebnisse, und in welcher Reihenfolge 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 lokale Bevölkerung und spiegeln gleichzeitig die Nutzereingaben wider. Vervollständigungen von Orten sind je nach Nutzereingabe in jeder Anfrage unterschiedlich formatiert.
    • Zuerst werden übereinstimmende Begriffe im Parameter input ausgewählt, wobei die Namen übereinstimmen mit der im Parameter languageCode angegebenen Spracheinstellung, wenn verwenden, während Sie andernfalls die Namen verwenden, die am besten zur Nutzereingabe passen.
    • Die Adressen sind in der Landessprache und in einem für den Nutzer lesbaren Script formatiert wenn möglich, erst, nachdem übereinstimmende Begriffe so ausgewählt wurden, dass sie mit den Begriffen im input-Parameter.
    • Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem die übereinstimmenden Begriffe Sie wurden so ausgewählt, dass sie den Begriffen im Parameter input entsprechen. Wenn ein Name nicht in der bevorzugten Sprache verfügbar ist, verwendet die API die genaueste Übereinstimmung.

• „locationBias“ oder „locationRestriction“

  Sie können locationBias oder locationRestriction angeben. aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sich locationRestriction vor, die Region, in der sich die Ergebnisse befinden müssen, und locationBias als Sie geben die Region an, in der sich die Ergebnisse befinden müssen, aber auch außerhalb liegen können in der Umgebung.

  • locationBias

    Gibt das Gebiet an, in dem gesucht werden soll. Dieser Standort dient als Verzerrung, können Ergebnisse im Umkreis des angegebenen Standorts zurückgegeben werden, einschließlich der Ergebnisse außerhalb des angegebenen Bereichs liegt.

  • locationRestriction

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

  Geben Sie die Region locationBias oder locationRestriction als rechteckigen Darstellungsbereich oder als Kreis.

  • Ein Kreis wird durch einen Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50000,0 (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 gibt die Anfrage Keine Ergebnisse.

    Beispiel:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

  • Ein Rechteck ist der Darstellungsbereich mit Breiten- und Längengraden, diagonal gegenüberliegend low und hohen Punkten. Ein Darstellungsbereich wird als geschlossene Region, d. h., sie umfasst ihre Begrenzung. Die Breitengradgrenzen muss zwischen -90 und einschließlich 90 Grad liegen und die Längengrenzen muss zwischen -180 und 180 Grad liegen:

    • Wenn low = high, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
    • Wenn low.longitude > high.longitude, der Längengradbereich ist invertiert (der Darstellungsbereich überschreitet 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, Längengradbereich ist 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
        }
      }
    }

• origin

  Der Ursprungspunkt, von dem aus die direkte Entfernung zum Ziel (zurückgegeben als distanceMeters). Wenn dieser Wert gleich ausgelassen, wird keine geradlinige Entfernung zurückgegeben. Muss angegeben werden als Längen- und Breitengrade:

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

• regionCode

  Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als ccTLD („Top-Level-Domain“) aus zwei Zeichen bestehen. Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes, mit einigen nennenswerten 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 des Vereinigten Königreichs Großbritannien und Nordirland“).

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

• sessionToken

  Sitzungstokens sind vom Nutzer erstellte Strings, die die automatische Vervollständigung erfassen (Neu) Aufrufe als „Sitzungen“. Bei Autocomplete (New) werden Sitzungstokens verwendet, um Gruppieren Sie die Abfrage- und Auswahlphasen einer Nutzersuche mit automatischer Vervollständigung in einer separaten Sitzung Abrechnungszwecke. 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, um die Ergebnisse zu gewichten. Sie können optional locationRestriction oder locationBias, aber nicht beides, um ein zu durchsuchendes Gebiet anzugeben.

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

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, d. h. Ergebnisse um den angegebenen Standort zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs. Im nächsten Beispiel: Sie ändern 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

Mit dem Parameter includedPrimaryTypes können Sie bis zu fünf Typwerte aus der Tabelle A, Tabelle B, oder nur (regions) oder nur (cities). Ein Ort muss mit einem der angegebenen Primärtypwerte, die in die Antwort aufgenommen werden sollen.

Im folgenden Beispiel geben Sie einen input-String von „Fußball“ und verwenden Sie den Parameter includedPrimaryTypes, um die Ergebnisse auf Einrichtungen des Typs "sporting_goods_store":

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 folgende Werte enthalten: Einrichtungen eines bestimmten Typs, wie z. B. "athletic_field".

Abfragevorhersagen anfordern

Vervollständigungen von Suchanfragen werden nicht standardmäßig zurückgegeben. includeQueryPredictions verwenden -Anfrageparameter, um der Antwort Suchanfragenvorhersagen 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 Vorhersage bei Abfragen enthält das Feld text mit einem empfohlenen Textsuchstring. Sie können eine Textsuche (neu) , um weitere Informationen zu den zurückgegebenen Abfragevorhersagen zu erhalten.

Ursprung verwenden

Fügen Sie in diesem Beispiel origin als Breiten- und Längengrad in die Anfrage ein. Wenn Sie origin einfügen, schließt die API das Feld distanceMeters in die Antwort, die die Luftlinie zwischen origin und dem 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
      }
    }
  ]
}

Testen!

Mit dem API Explorer können Sie Beispielanfragen stellen, damit Sie sich mit der API und den API-Optionen vertraut machen können.

1. Klicken Sie auf das API-Symbol . rechts auf der Seite.
2. Erweitern Sie optional Standardparameter anzeigen und legen Sie Parameter fields zur Feldmaske hinzu.
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 API Explorer auf das Symbol zum Maximieren , um das API Explorer-Fenster zu maximieren.