Place Autocomplete-Widget

Entwickler im Europäischen Wirtschaftsraum (EWR)

Das Place Autocomplete-Widget erstellt ein Texteingabefeld, liefert Ortsvorschläge in einer Auswahlliste und gibt Place Details als Reaktion auf die Auswahl des Nutzers zurück. Mit dem Place Autocomplete-Widget können Sie eine vollständige in sich geschlossene Benutzeroberfläche für die automatische Vervollständigung auf Ihrer Webseite einbetten. Die vollständige API-Referenz finden Sie unter PlaceAutocompleteElement.

Vorbereitung

Wenn Sie Place Autocomplete verwenden möchten, müssen Sie die Places API (New) in Ihrem Google Cloud Projekt aktivieren. Weitere Informationen finden Sie unter Erste Schritte.

Das ist neu

Place Autocomplete wurde in den folgenden Bereichen optimiert:

  • Die Benutzeroberfläche des Autocomplete-Widgets unterstützt die regionale Lokalisierung (einschließlich RTL-Sprachen) für den Texteingabeplatzhalter, das Logo der Liste mit Vorschlägen und die Ortsvorschläge.
  • Die Bedienungshilfen wurden weiter verbessert, einschließlich Unterstützung für Screenreader und Tastaturinteraktionen.
  • Das Autocomplete-Widget gibt die neue Place-Klasse (Place Referenz) zurück, um die Verarbeitung des zurückgegebenen Objekts zu vereinfachen.
  • Bessere Unterstützung für Mobilgeräte und kleine Bildschirme.
  • Bessere Leistung und grafische Darstellung.

Autocomplete-Widget hinzufügen

Das Autocomplete-Widget erstellt ein Texteingabefeld, liefert Orts vorschläge in einer Auswahlliste und gibt Ortsdetails als Reaktion auf Nutzer klicks über den gmp-select Listener zurück. In diesem Abschnitt wird beschrieben, wie Sie einer Webseite oder Google-Karte ein Autovervollständigungs-Widget hinzufügen.

Autocomplete-Widget auf einer Webseite einfügen

Wenn Sie das Autocomplete-Widget auf einer Webseite einfügen möchten, erstellen Sie ein neues google.maps.places.PlaceAutocompleteElement, und hängen Sie es an die Seite an. Hier ein Beispiel:

TypeScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);

JavaScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);

Vollständiges Codebeispiel ansehen

Karte ein Autocomplete-Widget hinzufügen

Wenn sich Ihre Rechnungsadresse außerhalb des Europäischen Wirtschaftsraums (EWR) befindet, können Sie das Autocomplete-Widget auch mit einer Google-Karte verwenden.

Wenn Sie einer Karte ein Autocomplete-Widget hinzufügen möchten, fordern Sie zuerst die erforderlichen Bibliotheken an. Hier ein Beispiel:

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

Verschachteln Sie dann in Ihrem HTML-Code ein neues gmp-place-autocomplete-Element in einem div und dieses div in einem gmp-map. Hier ein Beispiel:

<gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
    <div
        class="place-autocomplete-card"
        slot="control-inline-start-block-start">
        <gmp-place-autocomplete
            placeholder="Search for a place..."></gmp-place-autocomplete>
    </div>
</gmp-map>

Wenn Sie einer Karte programmatisch ein Autocomplete-Widget hinzufügen möchten, erstellen Sie eine neue google.maps.places.PlaceAutocompleteElement Instanz, hängen Sie das PlaceAutocompleteElement an ein div an und wenden Sie das Attribut slot auf das div an. Hier ein Beispiel: 

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

// Get the map element.
const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

// Create the PlaceAutocompleteElement instance.
const placeAutocomplete = new PlaceAutocompleteElement({});

// Create a div and append the PlaceAutocompleteElement to it.
const card = document.createElement("div");
card.appendChild(placeAutocomplete);

// Apply the slot attribute to the div.
// This positions the control in the top-left corner of the map.
card.setAttribute("slot", "control-inline-start-block-start");

// Append the div to the map element (check for null).
if (mapElement) {
    mapElement.appendChild(card);
}

Vollständiges Codebeispiel ansehen

Platzhaltertext hinzufügen

Verwenden Sie das placeholder Attribut, um Platzhaltertext hinzuzufügen. Im folgenden Beispiel wird gezeigt, wie Sie den Platzhaltertext in HTML festlegen:

<gmp-place-autocomplete
  placeholder="Search for a place..."
></gmp-place-autocomplete>

Sie können den Platzhaltertext auch programmatisch festlegen:

placeAutocomplete.placeholder = 'Search for a place...';

Automatische Vervollständigung einschränken

Standardmäßig werden bei Place Autocomplete alle Ortstypen angezeigt, wobei die Vorschläge nach Nähe zum Nutzerstandort gewichtet werden. Es werden alle verfügbaren Datenfelder für den vom Nutzer ausgewählten Ort abgerufen. Legen Sie PlaceAutocompleteElementOptions fest, um relevantere Vorschläge zu präsentieren. Dazu schränken Sie die Ergebnisse ein oder wenden eine Gewichtung an.

Werden die Ergebnisse eingeschränkt, ignoriert das Autocomplete-Widget alle Ergebnisse, die außerhalb des festgelegten Bereichs liegen. Häufig werden die Ergebnisse auf die Kartengrenzen beschränkt. Wenn Sie eine Gewichtung anwenden, zeigt das Autocomplete-Widget Ergebnisse innerhalb des angegebenen Bereichs an, einige können jedoch auch außerhalb liegen.

Wenn Sie weder Grenzen noch den Darstellungsbereich der Karte definieren, versucht die API, den Standort des Nutzers anhand seiner IP-Adresse zu ermitteln, und gewichtet die Ergebnisse nach diesem Standort. Legen Sie nach Möglichkeit Grenzen fest. Andernfalls sehen unterschiedliche Nutzer möglicherweise unterschiedliche Vorschläge. Um die Vorschläge generell zu verbessern, ist es außerdem wichtig, einen sinnvollen Darstellungsbereich festzulegen. Dieser kann z. B. durch Schwenken oder Zoomen der Karte ausgewählt oder vom Entwickler anhand des Gerätestandorts und eines entsprechenden Umkreises festgelegt werden. Wenn kein Umkreis angegeben ist, werden 5 km als sinnvoller Standardwert für Place Autocomplete betrachtet. Wählen Sie keinen Darstellungsbereich aus, der keinen Umkreis hat (d. h. keinen einzelnen Punkt), der einen Durchmesser von weniger als 100 Metern hat oder der den gesamten Globus umfasst.

Place Search-Ergebnisse nach Land einschränken

Wenn Sie die Place Search-Ergebnisse auf ein oder mehrere Länder beschränken möchten, verwenden Sie das includedRegionCodes Attribut, um die entsprechenden Ländercodes anzugeben. Im folgenden Snippet wird davon ausgegangen, dass Sie bereits eine Instanz mit dem Namen placeAutocomplete erstellt haben:

placeAutocomplete.includedRegionCodes = ['us', 'au'];;

Place Search-Ergebnisse auf Kartengrenzen beschränken

Wenn Sie die Place Search-Ergebnisse auf die Grenzen einer Karte beschränken möchten, verwenden Sie das locationRestriction Attribut. Das folgende Snippet zeigt, wie Sie einen Listener hinzufügen, damit die Grenzen bei Änderungen aktualisiert werden:

// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});

Um das locationRestriction, zu entfernen, legen Sie dafür null fest.

Gewichtung auf Place Search-Ergebnisse anwenden

Gewichten Sie die Place Search-Suchergebnisse auf einen kreisförmigen Bereich, indem Sie das locationBias Attribut verwenden, wie hier gezeigt:

placeAutocomplete.locationBias = {radius: 100, center: {lat: 40.749933, lng: -73.98633}};

Um das locationBias zu entfernen, legen Sie dafür null fest.

Place Search-Ergebnisse auf bestimmte Typen beschränken

Sie können die Place Search-Ergebnisse auf bestimmte Ortstypen beschränken. Dazu verwenden Sie das includedPrimaryTypes Attribut und geben einen oder mehrere Typen an. Hier ein Beispiel:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

Eine vollständige Liste der unterstützten Typen finden Sie in den Tabellen A und B zu Ortstypen.

Place Details abrufen

Fügen Sie dem PlaceAutocompleteElement einen gmp-select-Listener hinzu, um Place Details für den ausgewählten Ort abzurufen. Hier ein Beispiel:

TypeScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({
        placePrediction,
    }: google.maps.places.PlacePredictionSelectEvent) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);

JavaScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);

Vollständiges Codebeispiel ansehen

Im vorherigen Beispiel empfängt der Ereignis-Listener ein PlacePredictionSelectEvent und ruft placePrediction.toPlace() auf, um eine Instanz der Place-Klasse (Place Referenz) abzurufen. Rufen Sie place.fetchFields() auf, um die für Ihre Anwendung erforderlichen Place Details Datenfelder abzurufen.

Der Listener im nächsten Beispiel fordert Ortsinformationen an und präsentiert sie auf einer Karte.

TypeScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location!);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);

JavaScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);

Vollständiges Codebeispiel ansehen

Beispielkarten

Dieser Abschnitt enthält den vollständigen Code für die Beispielkarten auf dieser Seite.

Autocomplete-Element

In diesem Beispiel wird einer Webseite ein Autocomplete-Widget hinzugefügt. Außerdem werden die Ergebnisse für jeden ausgewählten Ort angezeigt.

TypeScript

async function init(): Promise<void> {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({
            placePrediction,
        }: google.maps.places.PlacePredictionSelectEvent) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();

JavaScript

async function init() {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

p {
    font-family: Roboto, sans-serif;
    font-weight: bold;
}

HTML

<html>
    <head>
        <title>Place Autocomplete element</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>
    </body>
</html>

Einer Karte ein Autocomplete-Widget hinzufügen

In diesem Beispiel wird gezeigt, wie Sie einer Google-Karte ein Autocomplete-Widget hinzufügen.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
const placeAutocomplete = document.querySelector('gmp-place-autocomplete')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function init(): Promise<void> {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds()!;
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

            // If the place has a geometry, then present it on a map.
            if (place.viewport) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location!);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            updateInfoWindow(content, place.location);
            marker.position = place.location;
        }
    );
}

// Helper function to create an info window.
function updateInfoWindow(
    content: string | Element | Text | null | undefined,
    center: google.maps.LatLng | google.maps.LatLngLiteral | null | undefined
) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

            // If the place has a geometry, then present it on a map.
            if (place.viewport) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            updateInfoWindow(content, place.location);
            marker.position = place.location;
        }
    );
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
gmp-map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

.place-autocomplete-card {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 5px;
    font-family: Roboto, sans-serif;
    font-size: small;
}

gmp-place-autocomplete {
    width: 300px;
}

#infowindow-content .title {
    font-weight: bold;
}

#map #infowindow-content {
    display: inline;
}

HTML

<html>
    <head>
        <title>Place Autocomplete map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <gmp-place-autocomplete
                    placeholder="Search for a place..."></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>

Autocomplete (New)-Optimierung

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

Allgemeine Richtlinien:

  • Am schnellsten lässt sich eine funktionsfähige Benutzeroberfläche mit dem Maps JavaScript API Autocomplete (New)-Widget, dem Places SDK for Android Autocomplete (New)-Widget, oder dem Places SDK for iOS Autocomplete (New)-Widget entwickeln.
  • Machen Sie sich zu Beginn mit den wichtigsten Datenfeldern von Autocomplete (New) 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 Autocomplete (New) Dienstes optimieren möchten, verwenden Sie Feldmasken in Place Details (New)- und Autocomplete (New)-Widgets, damit nur die Autocomplete (New) Datenfelder zurückgegeben werden, die Sie benötigen.

Erweiterte Kostenoptimierung

Wenn Sie Autocomplete (New) programmatisch implementieren, erhalten Sie Zugriff auf die Preise für die SKU „Autocomplete Request“ und können Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details (New)-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 (New)-Aufruf.
  • Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich maximal vier Autocomplete (New)-Anfragen auswählen, ist der Preis pro Anfrage möglicherweise kosteneffizienter als der Preis pro Sitzung.
Wenn Sie Hilfe bei der Auswahl der Autocomplete (New)-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 Autocomplete (New)-Modell mit Place Details (New)-Anfragen.
Da für Ihre Anwendung Place Details (New) erforderlich sind, etwa der Name des Orts, der Unternehmensstatus, oder die Öffnungszeiten, sollte bei der Implementierung von Autocomplete (New) ein Sitzungstoken (programmatisch oder im JavaScript, Android, oder iOS Widget integriert) verwendet werden. Dabei fallen Kosten pro Sitzung zzgl. der Kosten für die genutzten Places-SKUs an, je nachdem, welche Datenfelder angefordert werden.1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android, oder iOS -Widget integriert. Das umfasst sowohl Autocomplete (New)-Anfragen als auch die Place Details (New)-Anfrage für die ausgewählte Vervollständigung. Der fields Parameter muss festgelegt werden, damit nur die erforderlichen Autocomplete (New) Datenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-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 Autocomplete (New)-Antwort
  2. Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
  3. Den fields Parameter, mit dem die Autocomplete (New) Datenfelder angegeben werden, die Sie benötigen

Nein, es sind nur Adresse und Standort erforderlich.

Wenn Sie Autocomplete (New) in Ihrer Anwendung stark nutzen, kann es kostengünstiger sein, anstelle von Place Details (New) 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 eine Autocomplete (New)-Vervollständigung auswählen.

Wählen Ihre Nutzer durchschnittlich bei vier oder weniger Anfragen eine Autocomplete (New)-Vervollständigung aus?

Ja

Implementieren Sie Autocomplete (New) programmatisch ohne Sitzungstokens und rufen Sie die Geocoding API für die ausgewählte Ortsvervollständigung auf.
Über die Geocoding API erhalten Sie Adressen und Breiten-/Längenkoordinaten. Wenn vier Autocomplete-Anfragen mit Preis pro Anfrage ausgeführt werden und zusätzlich eine Geocoding API -Anfrage zum ausgewählten Ortsvorschlag gestellt wird, fallen weniger Kosten an als beim Preis pro Sitzung für Autocomplete (New) . 1

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

Nein

Nutzen Sie das sitzungsbasierte Autocomplete (New)-Modell mit Place Details (New)-Anfragen.
Da die durchschnittliche Anzahl der Anfragen, die voraussichtlich gestellt werden müssen, bevor ein Nutzer eine Autocomplete (New)-Vervollständigung auswählt, die Kosten pro Sitzung übersteigt, sollte Ihre Implementierung von Autocomplete (New) sowohl für Autocomplete (New)-Anfragen als auch für die zugehörigen Place Details (New)-Anfragen ein Sitzungstoken verwenden pro Sitzung. 1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android, oder iOS -Widget integriert. Das umfasst sowohl Autocomplete (New)-Anfragen als auch die Place Details (New) Anfrage für die ausgewählte Vervollständigung. Der Parameter fields muss festgelegt werden damit nur die erforderlichen Felder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-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 Autocomplete (New)-Antwort
  2. Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
  3. Den fields Parameter, mit dem grundlegende Datenfelder wie das Feld „Adresse“ oder „Geometrie“ angegeben werden

Autocomplete (New)-Anfragen verzögern
Sie können Autocomplete (New)-Anfragen verzögern, bis der Nutzer die ersten drei oder vier Zeichen eingegeben hat, damit weniger Anfragen über die Anwendung gestellt werden. Angenommen, Autocomplete (New)-Anfragen für jedes Zeichen werden erst gestellt, nachdem Nutzer drei Zeichen eingegeben hat. Wenn ein Nutzer sieben Zeichen eingibt und dann einen Vorschlag auswählt, für den eine Geocoding API-Anfrage gestellt wird, fallen Kosten für vier Autocomplete (New)-Anfragen mit Preis pro Anfrage und eine Geocoding-Anfrage an.

Wenn sich durch das Verzögern von Anfragen Ihre durchschnittliche Anzahl programmatischer Anfragen auf unter vier senken lässt, empfehlen wir, die Anleitung für eine leistungsstarke Autocomplete (New)-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. Informationen zu den Kosten finden Sie in den Preislisten der Google Maps Platform.

Best Practices für die Leistung

Im Folgenden finden Sie Tipps zum Optimieren der Autocomplete (New)-Leistung:

  • Binden Sie in Ihre Autocomplete (New) 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 Autocomplete (New) mit einer Karte kombiniert wird, können Sie den Standort anhand des Darstellungsbereichs der Karte gewichten.
  • Wenn ein Nutzer keinen der Autocomplete (New)-Vorschläge 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 Place Details (New)-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:
    • Wenn Nutzer Adressen für Untereinheiten eingeben, 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 Autocomplete (New) 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

Standortgewichtung

Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Bereichs gewichten. Dadurch werden von Autocomplete (New) vorzugsweise Ergebnisse für Orte angezeigt, die sich innerhalb dieses Bereichs befinden. Ergebnisse außerhalb dieses Bereichs können aber trotzdem noch angezeigt werden. Mit dem includedRegionCodes Parameter können Sie die Ergebnisse filtern , sodass nur Orte in einem bestimmten Land angezeigt werden.

Standortbeschränkung

Wenn Sie die Ergebnisse auf einen bestimmten Bereich beschränken möchten, geben Sie den Parameter locationRestriction weiter.

Sie können die Ergebnisse auch auf die Region beschränken, die durch location und einen radius Parameter definiert wird, indem Sie den locationRestriction Parameter hinzufügen. Dadurch werden von Autocomplete (New) nur Ergebnisse innerhalb dieser Region zurückgegeben.