Place Autocomplete

Plattform auswählen: Android iOS JavaScript Webdienst

Hinweis: Server- und clientseitige Bibliotheken

Die Places API ist auch mit den Java-, Python-, Go- und Node.js-Clients für Google Maps-Dienste verfügbar. Die Places API und die Clientbibliotheken sind für die Verwendung in Serveranwendungen vorgesehen.

Wenn Sie eine clientseitige Anwendung entwickeln, sehen Sie sich das Places SDK for Android, das Places SDK for iOS und die Places Library, Maps JavaScript API an.

Der Place Autocomplete-Dienst ist ein Webdienst, der Ortsvorschläge als Antwort auf eine HTTP-Anfrage zurückgibt. Die Anfrage enthält einen Suchstring und optionale geografische Grenzen. Mit dem Dienst können Sie eine automatische Vervollständigung für textbasierte geografische Suchanfragen bereitstellen, indem Sie Orte wie Unternehmen, Adressen und POIs zurückgeben, während der Nutzer tippt.

Place Autocomplete-Anfragen

Der Dienst „Place Autocomplete“ ist Teil der Places API und teilt sich einen API-Schlüssel und Kontingente mit der Places API.

Hinweis:Sie können Place Autocomplete auch ohne Karte verwenden. Falls Sie eine Karte anzeigen, muss es eine Google-Karte sein. Wenn Sie Vorschläge vom Place Autocomplete-Dienst ohne Karte anzeigen, muss das Google-Logo inline mit dem Suchfeld oder den Suchergebnissen angezeigt werden. Weitere Informationen finden Sie unter Google-Logo und Quellenangaben anzeigen.

Der Place Autocomplete-Dienst kann Übereinstimmungen mit vollständigen Wörtern und Teilstrings finden, sodass sich Ortsnamen, Adressen und Plus Codes zuordnen lassen. Anwendungen können Abfragen senden, während der Nutzer tippt, und schon bei der Eingabe Ortsvorschläge ausgeben.

Pluscodes müssen richtig formatiert sein. Das Pluszeichen muss also mit einem URL-Escape-Code in %2B und Leerzeichen mit einem URL-Escape-Code in %20 umgewandelt werden.

• Global Code besteht aus einer vierstelligen Ortsvorwahl und einem mindestens sechsstelligen lokalen Code. Der globale URL-Escape-Code für 849VCWC8+R9 lautet beispielsweise 849VCWC8%2BR9.
• Ein Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort. Beispiel: Der URL-entkommentierte zusammengesetzte Code CWC8+R9 Mountain View, CA, USA ist CWC8%2BR9%20Mountain%20View%20CA%20USA.

Die zurückgegebenen Vorhersagen sollen dem Nutzer bei der Auswahl des gewünschten Orts helfen. Sie können eine Place Details-Anfrage senden, um weitere Informationen zu den zurückgegebenen Orten zu erhalten.

Eine Place Autocomplete-Anfrage ist eine HTTP-URL der folgenden Form:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

Dabei kann output einen der folgenden Werte haben:

• json (empfohlen) gibt die Ausgabe in JSON (JavaScript Object Notation) an.
• xml gibt die Ausgabe als XML an

Zum Initiieren einer Place Autocomplete-Anfrage sind bestimmte Parameter erforderlich. Wie in URLs üblich, werden alle Parameter mit dem Und-Zeichen (&) getrennt. Die Liste der Parameter und ihre möglichen Werte finden Sie unten.

Required parameters

• input

  The text string on which to search. The Place Autocomplete service will return candidate matches based on this string and order results based on their perceived relevance.

Optional parameters

• components

  A grouping of places to which you would like to restrict your results. Currently, you can use components to filter by up to 5 countries. Countries must be passed as a two character, ISO 3166-1 Alpha-2 compatible country code. For example: components=country:fr would restrict your results to places within France. Multiple countries must be passed as multiple country:XX filters, with the pipe character | as a separator. For example: components=country:us|country:pr|country:vi|country:gu|country:mp would restrict your results to places within the United States and its unincorporated organized territories.

  Note: If you receive unexpected results with a country code, verify that you are using a code which includes the countries, dependent territories, and special areas of geographical interest you intend. You can find code information at Wikipedia: List of ISO 3166 country codes or the ISO Online Browsing Platform.

• language

  The language in which to return results.

  • See the list of supported languages. Google often updates the supported languages, so this list may not be exhaustive.
  • If language is not supplied, the API attempts to use the preferred language as specified in the Accept-Language header.
  • The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
  • If a name is not available in the preferred language, the API uses the closest match.
  • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.

• location

  The point around which to retrieve place information. This must be specified as latitude,longitude. The radius parameter must also be provided when specifying a location. If radius is not provided, the location parameter is ignored.

  When using the Text Search API, the `location` parameter may be overriden if the `query` contains an explicit location such as `Market in Barcelona`.

• locationbias

  Prefer results in a specified area, by specifying either a radius plus lat/lng, or two lat/lng pairs representing the points of a rectangle. If this parameter is not specified, the API uses IP address biasing by default.

  • IP bias: Instructs the API to use IP address biasing. Pass the string ipbias (this option has no additional parameters).
  • Circular: A string specifying radius in meters, plus lat/lng in decimal degrees. Use the following format: circle:radius@lat,lng.
  • Rectangular: A string specifying two lat/lng pairs in decimal degrees, representing the south/west and north/east points of a rectangle. Use the following format:rectangle:south,west|north,east. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.

• locationrestriction

  Restrict results to a specified area, by specifying either a radius plus lat/lng, or two lat/lng pairs representing the points of a rectangle.

  • Circular: A string specifying radius in meters, plus lat/lng in decimal degrees. Use the following format: circle:radius@lat,lng.
  • Rectangular: A string specifying two lat/lng pairs in decimal degrees, representing the south/west and north/east points of a rectangle. Use the following format:rectangle:south,west|north,east. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.

• offset

  The position, in the input term, of the last character that the service uses to match predictions. For example, if the input is Google and the offset is 3, the service will match on Goo. The string determined by the offset is matched against the first word in the input term only. For example, if the input term is Google abc and the offset is 3, the service will attempt to match against Goo abc. If no offset is supplied, the service will use the whole term. The offset should generally be set to the position of the text caret.

• origin

  The origin point from which to calculate straight-line distance to the destination (returned as distance_meters). If this value is omitted, straight-line distance will not be returned. Must be specified as latitude,longitude.

• radius

  Defines the distance (in meters) within which to return place results. You may bias results to a specified circle by passing a location and a radius parameter. Doing so instructs the Places service to prefer showing results within that circle; results outside of the defined area may still be displayed.

  The radius will automatically be clamped to a maximum value depending on the type of search and other parameters.

  • Autocomplete: 50,000 meters
  • Nearby Search:
    • with keyword or name: 50,000 meters
    • without keyword or name
      • Up to 50,000 meters, adjusted dynamically based on area density, independent of rankby parameter.
      • When using rankby=distance, the radius parameter will not be accepted, and will result in an INVALID_REQUEST.
  • Query Autocomplete: 50,000 meters
  • Text Search: 50,000 meters

• region

  The region code, specified as a ccTLD ("top-level domain") two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland").

• sessiontoken

  A random string which identifies an autocomplete session for billing purposes.

  The session begins when the user starts typing a query, and concludes when they select a place and a call to Place Details is made. Each session can have multiple queries, followed by one place selection. The API key(s) used for each request within a session must belong to the same Google Cloud Console project. Once a session has concluded, the token is no longer valid; your app must generate a fresh token for each session. If the sessiontoken parameter is omitted, or if you reuse a session token, the session is charged as if no session token was provided (each request is billed separately).

  We recommend the following guidelines:

  • Use session tokens for all autocomplete sessions.
  • Generate a fresh token for each session. Using a version 4 UUID is recommended.
  • Ensure that the API key(s) used for all Place Autocomplete and Place Details requests within a session belong to the same Cloud Console project.
  • Be sure to pass a unique session token for each new session. Using the same token for more than one session will result in each request being billed individually.

• strictbounds

  Returns only those places that are strictly within the region defined by location and radius. This is a restriction, rather than a bias, meaning that results outside this region will not be returned even if they match the user input.

• types

  You can restrict results from a Place Autocomplete request to be of a certain type by passing the types parameter. This parameter specifies a type or a type collection, as listed in Place Types. If nothing is specified, all types are returned.

  A place can only have a single primary type from types listed in Table 1 or Table 2. For example, a hotel where food is served may by returned only with types=lodging and not with types=restaurant.

  For the value of the types parameter you can specify either:

  • Up to five values from Table 1 or Table 2. For multiple values, separate each value with a | (vertical bar). For example:

    types=book_store|cafe

  • Any single supported filter in Table 3. You cannot mix type collections.

  Note: Although geocode and establishment are part of Table 2, they cannot be combined with any other type in Tables 1, 2, or 3 in Place Autocomplete request filters.

  The request will be rejected with an INVALID_REQUEST error if:

  • More than five types are specified.
  • Any unrecognized types are present.
  • Any types from in Table 1 or Table 2 are mixed with any of the filters in Table 3.
  Note: The types parameter only works on the primary type of the place, not all types associated with the place. Although every place has a primary type, not every primary type is supported by Places API (New). Supported types include those listed in Table 1 or Table 2.

Beispiele für Place Autocomplete

Eine Anfrage nach Unternehmen mit dem String „Amoeba“ in einem Gebiet mit Mittelpunkt in San Francisco, Kalifornien:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=amoeba
  &location=37.76999%2C-122.44696
  &radius=500
  &types=establishment
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

Dieselbe Anfrage, eingeschränkt auf Ergebnisse in einem Umkreis von 500 Metern um die Ashbury Street und die Haight Street in San Francisco:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=amoeba
  &location=37.76999%2C-122.44696
  &radius=500
  &strictbounds=true
  &types=establishment
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

Eine Anfrage für Adressen, die "Vict" enthalten, mit Ergebnissen in Französisch:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=Vict
  &language=fr
  &types=geocode
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Eine Anfrage nach Städten mit „Vict“ in den Ergebnissen auf Portugiesisch (Brasilien):

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=Vict
  &language=pt_BR
  &types=%28cities%29
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

Hinweis: Sie müssen den API-Schlüssel in diesen Beispielen durch Ihren eigenen Schlüssel ersetzen.

Place Autocomplete-Antwort

Antworten der automatischen Vervollständigung von Orten werden im Format zurückgegeben, das durch das output-Flag im URL-Pfad der Anfrage angegeben ist. Die folgenden Ergebnisse sind beispielhaft für das, was für eine Abfrage mit den folgenden Parametern zurückgegeben werden kann:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=Paris
  &types=geocode
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

Field	Required	Type	Description
predictions	required	Array<PlaceAutocompletePrediction>	Contains an array of predictions. See PlaceAutocompletePrediction for more information.
status	required	PlacesAutocompleteStatus	Contains the status of the request, and may contain debugging information to help you track down why the request failed. See PlacesAutocompleteStatus for more information.
error_message	optional	string	When the service returns a status code other than OK<, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.
info_messages	optional	Array<string>	When the service returns additional information about the request specification, there may be an additional info_messages field within the response object. This field is only returned for successful requests. It may not always be returned, and its content is subject to change.

Von besonderem Interesse sind die place_id-Elemente, mit denen über eine separate Abfrage genauere Details zum Ort angefordert werden können. Weitere Informationen finden Sie unter „Place Details“-Anfragen.

Eine XML-Antwort besteht aus einem einzelnen <AutocompletionResponse>-Element mit zwei Arten von untergeordneten Elementen:

• Ein einzelnes <status>-Element enthält Metadaten zur Anfrage. Weitere Informationen finden Sie unten im Abschnitt Statuscodes.
• Null oder mehr <prediction>-Elemente, die jeweils Informationen zu einem einzelnen Ort enthalten. Informationen zu diesen Ergebnissen finden Sie unter Place Autocomplete-Ergebnisse. Die Places API gibt bis zu fünf Ergebnisse zurück.

Wir empfehlen, json als bevorzugtes Ausgabeflag zu verwenden, es sei denn, Ihre Anwendung erfordert aus irgendeinem Grund xml. Die Verarbeitung von XML-Bäumen erfordert etwas Sorgfalt, damit Sie auf die richtigen Knoten und Elemente verweisen. Informationen zur Verarbeitung von XML finden Sie unter XML mit XPath verarbeiten.

Die Adresskomponente street_number ist in Place Details-Antworten für Orts-IDs möglicherweise nicht in allen automatischen Vervollständigungen enthalten. Das ist normalerweise der Fall, wenn die Adresse für einen Ort nicht interpoliert werden kann. In diesen Fällen enthält das types-Array des Vorschlags „route“. Bei automatischen Vervollständigungen mit einer Zahl in der Beschreibung (die eingegebene Anfrage stimmt überein) enthält die „Place Details“-Antwort für die Orts-ID nur dann die Hausnummer, wenn das types-Array für den Vorschlag mindestens eines der folgenden Elemente enthält:

• street_address
• premise
• establishment

PlacesAutocompleteStatus

Status codes returned by service.

• OK indicating the API request was successful.
• ZERO_RESULTS indicating that the search was successful but returned no results. This may occur if the search was passed a bounds in a remote location.
• INVALID_REQUEST indicating the API request was malformed, generally due to the missing input parameter.
• OVER_QUERY_LIMIT indicating any of the following:
  • You have exceeded the QPS limits.
  • Billing has not been enabled on your account.
  • The monthly $200 credit, or a self-imposed usage cap, has been exceeded.
  • The provided method of payment is no longer valid (for example, a credit card has expired).
  See the Maps FAQ for more information about how to resolve this error.
• REQUEST_DENIED indicating that your request was denied, generally because:
  • The request is missing an API key.
  • The key parameter is invalid.
• UNKNOWN_ERROR indicating an unknown error.

Wenn der Places-Dienst JSON-Ergebnisse aus einer Suche zurückgibt, werden sie in einem predictions-Array platziert. Auch wenn der Dienst keine Ergebnisse zurückgibt (z. B. wenn die location remote ist), wird ein leeres predictions-Array zurückgegeben. XML-Antworten bestehen aus null oder mehr <prediction>-Elementen.

PlaceAutocompletePrediction

Field	Required	Type	Description
description	required	string	Contains the human-readable name for the returned result. For establishment results, this is usually the business name. This content is meant to be read as-is. Do not programmatically parse the formatted address.
matched_substrings	required	Array<PlaceAutocompleteMatchedSubstring>	A list of substrings that describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired. See PlaceAutocompleteMatchedSubstring for more information.
structured_formatting	required	PlaceAutocompleteStructuredFormat	Provides pre-formatted text that can be shown in your autocomplete results. This content is meant to be read as-is. Do not programmatically parse the formatted address. See PlaceAutocompleteStructuredFormat for more information.
terms	required	Array<PlaceAutocompleteTerm>	Contains an array of terms identifying each section of the returned description (a section of the description is generally terminated with a comma). Each entry in the array has a value field, containing the text of the term, and an offset field, defining the start position of this term in the description, measured in Unicode characters. See PlaceAutocompleteTerm for more information.
distance_meters	optional	integer	The straight-line distance in meters from the origin. This field is only returned for requests made with an origin.
place_id	optional	string	A textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the placeId field of a Places API request. For more information about place IDs, see the Place IDs overview.
reference	optional	string	reference is deprecated. See place_id.
types	optional	Array<string>	Contains an array of types that apply to this place. For example: [ "political", "locality" ] or [ "establishment", "geocode", "beauty_salon" ]. The array can contain multiple values. Learn more about Place types.

PlaceAutocompleteMatchedSubstring

Field	Required	Type	Description
length	required	number	Length of the matched substring in the prediction result text.
offset	required	number	Start location of the matched substring in the prediction result text.

PlaceAutocompleteStructuredFormat

Field	Required	Type	Description
main_text	required	string	Contains the main text of a prediction, usually the name of the place.
main_text_matched_substrings	required	Array<PlaceAutocompleteMatchedSubstring>	Contains an array with offset value and length. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired. See PlaceAutocompleteMatchedSubstring for more information.
secondary_text	optional	string	Contains the secondary text of a prediction, usually the location of the place.
secondary_text_matched_substrings	optional	Array<PlaceAutocompleteMatchedSubstring>	Contains an array with offset value and length. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired. See PlaceAutocompleteMatchedSubstring for more information.

PlaceAutocompleteTerm

Field	Required	Type	Description
offset	required	number	Defines the start position of this term in the description, measured in Unicode characters
value	required	string	The text of the term.

Place Autocomplete-Optimierung

Hier finden Sie Best Practices, damit Sie den Place Autocomplete-Dienst optimal nutzen können.

Allgemeine Richtlinien:

• Am schnellsten lässt sich eine funktionsfähige Benutzeroberfläche mit dem Autocomplete-Widget der Maps JavaScript API, dem Autocomplete-Widget des Places SDK for Android oder dem UI-Steuerelement für die automatische Vervollständigung des Places SDK for iOS entwickeln.
• Machen Sie sich zu Beginn mit den wichtigsten Datenfeldern von Place Autocomplete vertraut.
• Die Felder zur Standortgewichtung und Standortbeschränkung sind optional, können aber erhebliche Auswirkungen auf die Leistung der automatischen Vervollständigung haben.
• Verwenden Sie die Fehlerbehandlung, wenn die API einen Fehler zurückgibt, damit die Anwendung fehlertolerant reagiert.
• Die Anwendung sollte Anfragen weiter verarbeiten und weiter funktionieren, auch wenn keine Auswahl getroffen wird.

Best Practices für die Kostenoptimierung

Einfache Kostenoptimierung

Wenn Sie die Kosten für die Nutzung des Place Autocomplete-Dienstes optimieren möchten, verwenden Sie Feldmasken in Place Details- und Place Autocomplete-Widgets, damit nur die erforderlichen Ortsdatenfelder zurückgegeben werden.

Erweiterte Kostenoptimierung

Wenn Sie Place Autocomplete programmatisch implementieren, erhalten Sie Zugriff auf die Preise pro Anfrage und können Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details-Ergebnissen anfordern. Wenn Sie die Kosten pro Anfrage mit der Geocoding API kombinieren, ist das kosteneffizienter als die Verwendung von Kosten pro Sitzung (sitzungsbasiert), sofern die beiden folgenden Bedingungen erfüllt werden:

• Wenn Sie nur den Breiten- und Längengrad oder die Adresse des vom Nutzer ausgewählten Orts abrufen möchten, erhalten Sie entsprechende Informationen über die Geocoding API, für die weniger Kosten anfallen als bei einem Place Details-Aufruf.
• Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich maximal 4 entsprechenden Anfragen auswählen, ist der Preis pro Anfrage möglicherweise kosteneffizienter als der Preis pro Sitzung.

Wenn Sie Hilfe bei der Auswahl der Place Autocomplete-Implementierung benötigen, klicken Sie auf den Tab, der Ihrer Antwort auf die folgende Frage am ehesten entspricht.

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

Ja, weitere Details sind erforderlich.

Nutzen Sie das sitzungsbasierte Place Autocomplete-Modell mit Place Details-Anfragen.
Da für Ihre Anwendung Place Details erforderlich sind, etwa der Name des Orts, der Unternehmensstatus oder die Öffnungszeiten, sollte bei der Implementierung von Place Autocomplete ein Sitzungstoken (programmatisch oder im JavaScript-, Android- oder iOS-Widget integriert) verwendet werden. Dabei fallen insgesamt 0,017 $ pro Sitzung zzgl. der Kosten für die genutzten Places-Daten-SKUs an, je nachdem, welche Datenfelder angefordert werden.¹

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript-, Android- oder iOS-Widget integriert. Das umfasst sowohl Place Autocomplete-Anfragen als auch die Place Details-Anfrage für den ausgewählten Vorschlag. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Ortsdatenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Place Autocomplete-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Details zum Ort für den ausgewählten Vorschlag anfordern:

1. Die Orts-ID aus der Place Autocomplete-Antwort
2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage verwendet wird
3. Den fields-Parameter, mit dem die erforderlichen Ortsdatenfelder angegeben werden

Nein, es sind nur Adresse und Standort erforderlich.

Wenn Sie Place Autocomplete in Ihrer Anwendung stark nutzen, kann es kostengünstiger sein, anstelle von Place Details die Geocoding API zu verwenden. Die Effizienz der Autovervollständigung jeder Anwendung hängt davon ab, was die Nutzer eingeben, wo die Anwendung verwendet wird und ob die Best Practices zur Leistungsoptimierung implementiert wurden.

Um die folgende Frage beantworten zu können, analysieren Sie, wie viele Zeichen Nutzer durchschnittlich eingeben, bevor sie in Ihrer Anwendung einen Place Autocomplete-Vorschlag auswählen.

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

Ja

Implementieren Sie Place Autocomplete programmatisch ohne Sitzungstokens und rufen Sie die Geocoding API für den ausgewählten Ortsvorschlag auf.
Über die Geocoding API erhalten Sie Adressen und Breiten-/Längenkoordinaten für 0,005 $ pro Anfrage. Wenn 4 Place Autocomplete-Anfragen mit Preis pro Anfrage ausgeführt werden, fallen Kosten von 0,01132 $ an. Die Gesamtkosten der 4 Anfragen plus die Kosten für einen Geocoding API-Aufruf zum ausgewählten Ortsvorschlag betragen 0,01632 $, also weniger als der Preis pro Sitzung mit automatischer Vervollständigung von 0,017 $ pro Sitzung.¹

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

Nein

Nutzen Sie das sitzungsbasierte Place Autocomplete-Modell mit Place Details-Anfragen.
Die Kosten für die durchschnittliche Anzahl der Anfragen, die voraussichtlich gestellt werden müssen, bevor ein Nutzer einen Place Autocomplete-Vorschlag auswählt, übersteigen den Preis pro Sitzung. Daher sollte Ihre Place Autocomplete-Implementierung sowohl für Place Autocomplete-Anfragen als auch zugehörige Place Details-Anfragen ein Sitzungstoken nutzen, für das insgesamt 0,017 $ pro Sitzung anfallen.¹

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript-, Android- oder iOS-Widget integriert. Das umfasst sowohl Place Autocomplete-Anfragen als auch die Place Details-Anfrage für den ausgewählten Vorschlag. Der fields-Parameter muss festgelegt werden, damit nur die grundlegenden Datenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Place Autocomplete-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Details zum Ort für den ausgewählten Vorschlag anfordern:

1. Die Orts-ID aus der Place Autocomplete-Antwort
2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage verwendet wird
3. Den fields-Parameter, mit dem grundlegende Datenfelder wie das Feld „Adresse“ oder „Geometrie“ angegeben werden

Place Autocomplete-Anfragen verzögern
Sie können Place Autocomplete-Anfragen verzögern, bis der Nutzer die ersten 3 oder 4 Zeichen eingegeben hat, damit weniger Anfragen über die Anwendung gestellt werden. Angenommen, Place Autocomplete-Anfragen für jedes Zeichen werden erst gestellt, nachdem Nutzer 3 Zeichen eingegeben hat. Wenn ein Nutzer 7 Zeichen eingibt und dann einen Vorschlag auswählt, für den eine Geocoding API-Anfrage gestellt wird, fallen insgesamt Kosten von 0,01632 $ an (4 × 0,00283 $ pro Autocomplete-Anfrage + 0,005 $ für die Geocoding-Anfrage).¹

Wenn sich durch das Verzögern von Anfragen Ihre durchschnittliche Anzahl programmatischer Anfragen auf unter 4 senken lässt, empfehlen wir, die Anleitung für eine leistungsstarke Place Autocomplete-Funktion mit Geocoding API-Implementierung zu beachten. Das Verzögern von Anfragen wird vom Nutzer, der evtl. bei jedem eingegebenen Zeichen mit Vorschlägen rechnet, möglicherweise als Latenz wahrgenommen.

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

---

1. Die hier aufgeführten Kosten sind in US-Dollar angegeben. Vollständige Preisinformationen finden Sie auf der Seite Google Maps Platform – Abrechnung.

Best Practices für die Leistung

Im Folgenden finden Sie Tipps zum Optimieren der Place Autocomplete-Leistung:

• Binden Sie in Ihre Place Autocomplete-Implementierung länderspezifische Einschränkungen, eine Standortgewichtung und (bei programmatischen Implementierungen) eine Spracheinstellung ein. Die Spracheinstellung ist bei Widgets nicht erforderlich, weil bei ihnen die Spracheinstellungen aus dem Browser oder vom Mobilgerät des Nutzers übernommen werden.
• Wenn Place Autocomplete mit einer Karte kombiniert wird, können Sie den Standort anhand des Darstellungsbereichs der Karte gewichten.
• Wenn ein Nutzer keinen der Vorschläge der automatischen Vervollständigungen auswählt, was in der Regel geschieht, wenn es sich bei keinem Vorschlag um die gewünschte Adresse handelt, können Sie anhand der ursprünglichen Nutzereingabe versuchen, relevantere Ergebnisse zu erhalten:
  • Wenn der Nutzer voraussichtlich nur Adressinformationen eingibt, können Sie die ursprüngliche Nutzereingabe bei einem Aufruf der Geocoding API noch einmal verwenden.
  • Wenn Sie davon ausgehen, dass der Nutzer Abfragen für einen bestimmten Ort mithilfe von Name oder Adresse eingibt, verwenden Sie eine Find Place-Anfrage. Wenn nur in einer bestimmten Region Ergebnisse erwartet werden, nutzen Sie die Standortgewichtung.
  Bei folgenden Szenarien empfehlen wir, ein Fallback auf die Geocoding API zu nutzen:
  • Nutzer geben Adressen für untergeordnete Räumlichkeiten ein, z. B. Adressen für bestimmte Einheiten oder Wohnungen in einem Gebäude. So wird bei der tschechischen Adresse „Stroupežnického 3191/17, Praha“ z. B. eine teilweise Vervollständigung in Place Autocomplete ausgegeben.
  • Wenn Nutzer Adressen mit Präfixen für Straßenabschnitte eingeben, z. B. „23-30 29th St, Queens“ in New York City oder „47-380 Kamehameha Hwy, Kaneohe“ auf der Insel Kauai in Hawaii

Standortverzerrung

Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Bereichs gewichten. Dadurch werden vom Place Autocomplete-Dienst vorzugsweise Ergebnisse für Orte angezeigt, die sich innerhalb des definierten Bereichs befinden. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter components können Sie die Ergebnisse so filtern, dass nur Orte in einem bestimmten Land angezeigt werden.

Warnung:Wenn radius nicht angegeben ist, wird der Parameter location ignoriert.

Tipp:Ergebnisse für Unternehmen sind in der Regel nicht hoch genug, um in den Ergebnissen angezeigt zu werden, wenn der Suchbereich groß ist. Wenn Sie möchten, dass Unternehmen in gemischten Ergebnissen für Unternehmen und Geocodes erscheinen, können Sie einen kleineren Radius angeben. Alternativ können Sie types=establishment verwenden, um die Ergebnisse auf Unternehmen zu beschränken.

Standorteinschränkungen

Sie können die Ergebnisse auf einen bestimmten Bereich beschränken, indem Sie einen locationrestriction-Parameter übergeben.

Sie können die Ergebnisse auch auf die Region beschränken, die durch den Parameter location und einen radius-Parameter definiert ist. Dazu fügen Sie den Parameter strictbounds hinzu. Dadurch wird der Place Autocomplete-Dienst angewiesen, nur Ergebnisse innerhalb dieser Region zurückzugeben.

Hinweis:Standortbeschränkungen werden nur auf ganze Routen angewendet. Künstlich erzeugte Ergebnisse außerhalb der Standortbeschränkung können auf der Grundlage einer Route zurückgegeben werden, die sich mit der Standortbeschränkung überschneidet.