Widżet Autouzupełniania miejsc

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Jeśli Twój adres rozliczeniowy znajduje się w Europejskim Obszarze Gospodarczym, od 8 lipca 2025 r. do korzystania z usług będą miały zastosowanie Warunki korzystania z usługi Google Maps Platform w EOG. Funkcje różnią się w zależności od regionu. Więcej informacji

Widżet autouzupełniania miejsc tworzy pole do wprowadzania danych, podaje podpowiedzi miejsc na liście wyboru w interfejsie i zwraca informacje o miejscu w odpowiedzi na wybór użytkownika. Użyj widżetu autouzupełniania miejsc, aby umieścić na stronie internetowej kompletny, samodzielny interfejs autouzupełniania. Pełną dokumentację interfejsu API znajdziesz na stronie PlaceAutocompleteElement.

Wymagania wstępne

Aby korzystać z autouzupełniania miejsc, musisz włączyć Places API (New) w projekcie Google Cloud. Więcej informacji znajdziesz w artykule Pierwsze kroki.

Nowości

Autouzupełnianie miejsc zostało ulepszone w następujący sposób:

• Interfejs widżetu autouzupełniania obsługuje lokalizację regionalną (w tym języki zapisywane od prawej do lewej) w przypadku obiektu zastępczego do wpisywania tekstu, logo listy podpowiedzi i podpowiedzi miejsc.
• Ulepszone ułatwienia dostępu, w tym obsługa czytników ekranu i interakcji za pomocą klawiatury.
• Widżet autouzupełniania zwraca nową klasę Place (Place), aby uprościć obsługę zwracanego obiektu.
• Lepsza obsługa urządzeń mobilnych i małych ekranów.
• Wyższa wydajność i lepszy wygląd graficzny.

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania tworzy pole do wprowadzania danych, podaje podpowiedzi miejsc na liście wyboru w interfejsie i zwraca informacje o miejscu w odpowiedzi na kliknięcie użytkownika za pomocą detektora gmp-select. Z tej sekcji dowiesz się, jak dodać widżet autouzupełniania do strony internetowej lub mapy Google.

Dodawanie widżetu autouzupełniania do strony internetowej

Aby dodać widżet autouzupełniania do strony internetowej, utwórz nowy element google.maps.places.PlaceAutocompleteElement i dołącz go do strony, jak pokazano w tym przykładzie:

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);
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

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);
index.js

Zobacz pełny przykład kodu

Dodawanie widżetu autouzupełniania do mapy

Jeśli Twój adres rozliczeniowy znajduje się poza Europejskim Obszarem Gospodarczym (EOG), możesz też używać widżetu autouzupełniania z Mapami Google.

Aby dodać do mapy widżet autouzupełniania, najpierw poproś o potrzebne biblioteki, jak pokazano poniżej:

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

Następnie w kodzie HTML umieść nowy element gmp-place-autocomplete w elemencie div, a ten element div w elemencie gmp-map, jak w tym przykładzie:

<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>
index.html

Aby automatycznie dodać widżet autouzupełniania do mapy, utwórz nową instancję google.maps.places.PlaceAutocompleteElement, dołącz PlaceAutocompleteElement do div i zastosuj atrybut slot do div, jak w tym przykładzie:

// 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);
}

Zobacz pełny przykład kodu

Dodaj tekst zastępczy

Aby dodać tekst zastępczy, użyj właściwości placeholder. W przykładzie poniżej pokazujemy, jak ustawić tekst zastępczy w kodzie HTML:

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

Tekst zastępczy możesz też ustawić automatycznie:

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

Ograniczanie podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc wyświetla wszystkie typy miejsc, faworyzując podpowiedzi w pobliżu lokalizacji użytkownika, i pobiera wszystkie dostępne pola danych dla wybranego przez użytkownika miejsca. Ustaw PlaceAutocompleteElementOptions, aby wyświetlać trafniejsze podpowiedzi, ograniczając lub faworyzując wyniki.

Ograniczenie wyników powoduje, że widżet Autouzupełniania ignoruje wszystkie wyniki znajdujące się poza obszarem ograniczeń. Powszechną praktyką jest ograniczanie wyników do granic mapy. Dzięki temu widżet autouzupełniania będzie wyświetlać wyniki w określonym obszarze, ale niektóre dopasowania mogą znajdować się poza nim.

Jeśli nie podasz żadnych granic ani widocznego obszaru mapy, interfejs API spróbuje wykryć lokalizację użytkownika na podstawie jego adresu IP i będzie faworyzować wyniki z tej lokalizacji. Jeśli to możliwe, ustaw granice. W przeciwnym razie różni użytkownicy mogą otrzymywać różne podpowiedzi. Aby ogólnie poprawić podpowiedzi, warto podać odpowiedni widoczny obszar, np. ustawiony przez przesuwanie lub powiększanie mapy, albo widoczny obszar ustawiony przez dewelopera na podstawie lokalizacji urządzenia i promienia. Jeśli promień nie jest dostępny, w przypadku autouzupełniania miejsc za rozsądną wartość domyślną uznaje się 5 km. Nie ustawiaj widocznego obszaru o zerowym promieniu (pojedynczy punkt), widocznego obszaru o szerokości zaledwie kilku metrów (mniej niż 100 metrów) ani widocznego obszaru obejmującego cały świat.

Ograniczanie wyszukiwania miejsc według kraju

Aby ograniczyć wyszukiwanie miejsc do jednego lub kilku konkretnych krajów, użyj właściwości includedRegionCodes, aby określić kody krajów, jak pokazano w tym fragmencie kodu (zakładamy, że masz już utworzoną instancję o nazwie placeAutocomplete):

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

Ograniczanie wyszukiwania miejsc do granic mapy

Aby ograniczyć wyszukiwanie miejsc do granic mapy, użyj właściwości locationRestriction. Poniższy fragment kodu pokazuje, jak dodać detektor, który będzie aktualizować granice, gdy się zmienią:

// 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();
});

Aby usunąć locationRestriction, ustaw wartość null.

Wpływanie na wyniki wyszukiwania miejsc

Aby zawęzić wyniki wyszukiwania miejsc do obszaru kołowego, użyj właściwości locationBias, jak pokazano poniżej:

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

Aby usunąć locationBias, ustaw wartość null.

Ograniczanie wyników wyszukiwania miejsc do określonych typów

Ogranicz wyniki wyszukiwania miejsc do określonych typów miejsc, używając właściwości includedPrimaryTypes i określając co najmniej 1 typ, jak pokazano poniżej:

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

Pełną listę obsługiwanych typów znajdziesz w tabelach A i B z typami miejsc.

Uzyskiwanie informacji o miejscu

Aby uzyskać informacje o miejscu dla wybranego miejsca, dodaj detektor gmp-select do PlaceAutocompleteElement, jak pokazano w tym przykładzie:

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
        );
    }
);
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

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
        );
    }
);
index.js

Zobacz pełny przykład kodu

W poprzednim przykładzie detektor zdarzeń otrzymuje PlacePredictionSelectEvent i wywołuje placePrediction.toPlace(), aby uzyskać instancję klasy Place (odwołanie Place). Wywołaj place.fetchFields(), aby uzyskać pola danych ze szczegółowymi informacjami o miejscu, których potrzebuje Twoja aplikacja.

Detektor w następnym przykładzie żąda pól displayName, formattedAddress, location i viewport w place.fetchFields(), a następnie używa place.viewport z fitBounds(), aby wyświetlić wybrane miejsce na mapie.

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;
    }
);
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

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;
    }
);
index.js

Zobacz pełny przykład kodu

Przykładowe mapy

Ta sekcja zawiera pełny kod przykładowych map przedstawionych na tej stronie.

Element autouzupełniania

Ten przykład dodaje widżet autouzupełniania do strony internetowej i wyświetla wyniki dla każdego wybranego miejsca.

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();
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

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();
index.js

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;
}
style.css

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>
index.html

Mapa autouzupełniania

Ten przykład pokazuje, jak dodać widżet autouzupełniania do mapy Google.

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();
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

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();
index.js

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;
}
style.css

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>
index.html

Optymalizacja autouzupełniania (nowa wersja)

W tej sekcji opisujemy sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi Autouzupełnianie (nowa).

Oto ogólne wskazówki:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) z Maps JavaScript API, widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na iOS.
• Od samego początku poznaj najważniejsze pola danych autouzupełniania (nowej wersji).
• Pola ukierunkowania na lokalizację i ograniczenia lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie autouzupełniania.
• Użyj obsługi błędów, aby upewnić się, że aplikacja będzie działać prawidłowo, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuację, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi Autouzupełnianie (nowa), użyj masek pól w widżetach informacje o miejscu (nowe) i Autouzupełnianie (nowe), aby zwracać tylko potrzebne pola danych Autouzupełniania (nowego).

Zaawansowana optymalizacja kosztów

Rozważ automatyczne wdrożenie autouzupełniania (nowego), aby uzyskać dostęp do SKU: ceny żądań autouzupełniania i poprosić o wyniki Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (nowych). Ceny za żądanie w połączeniu z Geocoding API są bardziej opłacalne niż ceny za sesję, jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu miejsca wybranego przez użytkownika, Geocoding API dostarcza te informacje za mniej niż wywołanie informacji o miejscu (New).
• Jeśli użytkownicy wybierają podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań podpowiedzi autouzupełniania (nowych), ceny za żądanie mogą być bardziej opłacalne niż ceny za sesję.

Aby wybrać implementację autouzupełniania (nową), która będzie najtańsza dla Twojej aplikacji, znajdź w poniższej tabeli wiersz odpowiadający potrzebom aplikacji.

Co musi zawierać Twoje zgłoszenie	Średnia liczba żądań autouzupełniania (nowego) przed wybraniem podpowiedzi przez użytkownika	Zalecana implementacja
informacje o miejscu inne niż adres i lokalizacja, takie jak nazwa miejsca, stan firmy lub godziny otwarcia;	Dowolna liczba	Autouzupełnianie (nowe) oparte na sesji z informacjami o miejscu (nowymi)
Tylko adres i szerokość/długość geograficzna wybranej podpowiedzi	4 lub mniej	Autouzupełnianie (nowe) na żądanie z interfejsem Geocoding API
Tylko adres i szerokość/długość geograficzna wybranej podpowiedzi	Więcej niż 4	Autouzupełnianie (nowe) oparte na sesjach w aplikacjach, które korzystają tylko z adresów

W zależności od wydajności Autouzupełniania (nowego) interfejs Geocoding API może być dla Twojej aplikacji bardziej opłacalny niż informacje o miejscu (nowe). Skuteczność autouzupełniania (nowego) w każdej aplikacji zależy od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji skuteczności.

Aby znaleźć średnią liczbę żądań dla tabeli, przeanalizuj, ile znaków użytkownik wpisuje średnio przed wybraniem podpowiedzi autouzupełniania (nowej) w aplikacji.

Autouzupełnianie (nowe) oparte na sesji z informacjami o miejscu (nowe)

Używaj autouzupełniania opartego na sesji (nowego) z informacjami o miejscu (nowymi).
Ponieważ Twoja aplikacja wymaga informacji o miejscu (nowych), takich jak nazwa miejsca, status firmy lub godziny otwarcia, Twoja implementacja autouzupełniania (nowego) powinna używać tokena sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS) na sesję oraz odpowiednich kodów SKU Miejsc, w zależności od tego, o które pola danych miejsca prosisz¹.

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania dotyczące informacji o miejscu (nowe) w przypadku wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko tych pól danych autouzupełniania (nowego), których potrzebujesz.

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). W żądaniu informacji o miejscu (nowych) dotyczących wybranej podpowiedzi uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający potrzebne pola danych autouzupełniania (nowego).

Autouzupełnianie (nowe) na żądanie z Geocoding API

Zaimplementuj Autouzupełnianie (nowe) automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku wybranej podpowiedzi miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wykonanie 4 żądań autouzupełniania i wywołanie Geocoding API w przypadku wybranej podpowiedzi miejsca kosztuje mniej niż autouzupełnianie (nowe) na sesję.¹

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby ułatwić użytkownikom uzyskiwanie podpowiedzi, których szukają, przy użyciu jeszcze mniejszej liczby znaków.

Autouzupełnianie (nowe) oparte na sesjach w przypadku aplikacji, które korzystają tylko z adresów

Używaj autouzupełniania opartego na sesji (nowego) z informacjami o miejscu (nowymi).
Średnia liczba żądań, których oczekujesz, zanim użytkownik wybierze podpowiedź autouzupełniania (nowego), przekracza koszt rozliczania za sesję, dlatego Twoja implementacja autouzupełniania (nowego) powinna używać tokena sesji zarówno w przypadku żądań autouzupełniania (nowego), jak i powiązanych żądań informacji o miejscu (nowych) za sesję. ¹

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania dotyczące informacji o miejscu (nowe) w przypadku wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko tych pól, których potrzebujesz.

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). Gdy prosisz o informacje o miejscu (nowe) dotyczące wybranej podpowiedzi, uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający pola, takie jak adres i geometria.

Rozważ opóźnienie żądań autouzupełniania (nowa wersja)
Możesz zastosować strategie takie jak opóźnienie żądania autouzupełniania (nowa wersja), dopóki użytkownik nie wpisze pierwszych 3 lub 4 znaków, dzięki czemu aplikacja będzie wysyłać mniej żądań. Jeśli na przykład wysyłasz żądania Autouzupełniania (nowego) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku, oznacza to, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze podpowiedź, dla której wysyłasz jedno żądanie do interfejsu Geocoding API, łączny koszt będzie obejmował 4 żądania Autouzupełniania (nowego) i żądanie do interfejsu Geocoding API¹.

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań automatycznych spadnie poniżej 4, możesz postępować zgodnie ze wskazówkami dotyczącymi implementacji wydajnego autouzupełniania (nowego) z interfejsem Geocoding API. Pamiętaj, że opóźnianie żądań może być postrzegane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać podpowiedź, której szukają, przy użyciu mniejszej liczby znaków.

---

1. Koszty znajdziesz w cennikach Google Maps Platform.

Sprawdzone metody dotyczące skuteczności

Te wskazówki opisują sposoby optymalizacji wydajności autouzupełniania (nowego):

• Dodaj do implementacji Autouzupełniania (nowego) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) ustawienia języka. Ustawienia języka nie są potrzebne w przypadku widżetów, ponieważ pobierają one ustawienia języka z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianiu (nowemu) towarzyszy mapa, możesz zmienić lokalizację według widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (nowego), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć oryginalnych danych wejściowych użytkownika, aby spróbować uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie oryginalnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli spodziewasz się, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacji o miejscu (nowego). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których najlepiej jest użyć Geocoding API:
  • Użytkownicy wpisują adresy podlokali, np. adresy konkretnych lokali lub mieszkań w budynku. Na przykład czeski adres „Stroupežnického 3191/17, Praha” zwraca częściową podpowiedź w Autouzupełnianiu (nowym).
  • Użytkownicy wpisują adresy z prefiksami segmentów dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Uwzględnianie lokalizacji

Możesz faworyzować wyniki z określonego obszaru, przekazując parametry location i radius. Dzięki temu autouzupełnianie (nowe) będzie preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru includedRegionCodes, aby filtrować wyniki i wyświetlać tylko miejsca w określonym kraju.

Ostrzeżenie: jeśli nie podasz parametru radius, parametr location zostanie zignorowany.

Wyniki dotyczące placówek zwykle nie są na tyle wysoko w rankingu, aby wyświetlać się w wynikach, gdy obszar wyszukiwania jest duży. Jeśli chcesz, aby placówki pojawiały się w wynikach mieszanych (placówki i kody geograficzne), możesz określić mniejszy promień. Możesz też użyć parametru types=establishment, aby ograniczyć wyniki tylko do placówek.

Ograniczanie lokalizacji

Ogranicz wyniki do określonego obszaru, przekazując parametr locationRestriction.

Możesz też ograniczyć wyniki do regionu określonego przez parametry location i radius, dodając parametr locationRestriction. Dzięki temu autouzupełnianie (nowe) zwraca wyniki tylko z tego regionu.

Uwaga: ograniczenia dotyczące lokalizacji są stosowane tylko do całych tras. Wyniki syntetyczne znajdujące się poza ograniczeniem lokalizacji mogą być zwracane na podstawie trasy, która pokrywa się z ograniczeniem lokalizacji.