Interfejs Place Autocomplete Data API

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

Interfejs Place Autocomplete Data API umożliwia programowe pobieranie prognozowanych miejsc, co pozwala na tworzenie dostosowanych funkcji autouzupełniania z większą kontrolą niż w przypadku widżetu autouzupełniania. Z tego przewodnika dowiesz się, jak używać interfejsu Place Autocomplete Data API do wysyłania żądań autouzupełniania miejsc na podstawie zapytań użytkowników.

Poniższy przykład pokazuje uproszczoną integrację podpowiedzi. Wpisz zapytanie, np. „pizza” lub „poke”, a następnie kliknij, aby wybrać odpowiedni wynik.

Żądania autouzupełniania

Żądanie autouzupełniania przyjmuje ciąg wejściowy zapytania i zwraca listę podpowiedzi miejsc. Aby wysłać żądanie autouzupełniania, wywołaj fetchAutocompleteSuggestions() i przekaż żądanie z wymaganymi właściwościami. Właściwość input zawiera ciąg znaków do wyszukania. W typowej aplikacji ta wartość jest aktualizowana, gdy użytkownik wpisuje zapytanie. Żądanie powinno zawierać parametr sessionToken, który jest używany do celów rozliczeniowych.

Poniższy fragment kodu pokazuje, jak utworzyć treść żądania i dodać token sesji, a następnie wywołać funkcję fetchAutocompleteSuggestions(), aby uzyskać listę obiektów PlacePrediction.

// Add an initial request body.
const request = {
    input: 'Tadi',
    locationRestriction: {
        west: -122.44,
        north: 37.8,
        east: -122.39,
        south: 37.78,
    },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ['restaurant'],
    language: 'en-US',
    region: 'us',
};

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
request.sessionToken = token;
index.js

Ograniczanie podpowiedzi autouzupełniania

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

Ograniczenie wyników powoduje, że widżet autouzupełniania ignoruje wszystkie wyniki, które znajdują się poza obszarem ograniczenia. 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.

Użyj właściwości origin, aby określić punkt początkowy, od którego ma być obliczana odległość geodezyjna do miejsca docelowego. Jeśli ta wartość zostanie pominięta, odległość nie zostanie zwrócona.

Użyj właściwości includedPrimaryTypes, aby określić maksymalnie 5 typów miejsc. Jeśli nie podasz żadnych typów, zostaną zwrócone miejsca wszystkich typów.

Zobacz dokumentację API

Uzyskiwanie informacji o miejscu

Aby zwrócić obiekt Place z wyniku podpowiedzi miejsca, najpierw wywołaj toPlace(), a następnie wywołaj fetchFields() na wynikowym obiekcie Place (identyfikator sesji z podpowiedzi miejsca jest uwzględniany automatycznie). Wywołanie metody fetchFields() kończy sesję autouzupełniania.

const place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});

const placeInfo = document.getElementById('prediction');
placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
index.js

Tokeny sesji

Tokeny sesji grupują fazy zapytania i wyboru wyszukiwania z autouzupełnianiem przez użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna pisać. Sesja kończy się, gdy użytkownik wybierze miejsce i zostanie wywołana usługa informacji o miejscu.

Aby utworzyć nowy token sesji i dodać go do żądania, utwórz instancję AutocompleteSessionToken, a następnie ustaw właściwość sessionToken żądania tak, aby używała tokenów, jak pokazano w tym fragmencie kodu:

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
request.sessionToken = token;
index.js

Sesja kończy się po wywołaniu metody fetchFields(). Po utworzeniu instancji Place nie musisz przekazywać tokena sesji do fetchFields(), ponieważ jest to obsługiwane automatycznie.

await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});
index.js

Utwórz token sesji dla następnej sesji, tworząc nową instancję AutocompleteSessionToken.

Rekomendacje dotyczące tokena sesji:

• Używaj tokenów sesji we wszystkich wywołaniach autouzupełniania miejsc.
• Generuj nowy token dla każdej sesji.
• Przekaż unikalny token sesji dla każdej nowej sesji. Użycie tego samego tokena w więcej niż 1 sesji spowoduje, że każde żądanie będzie rozliczane osobno.

Możesz opcjonalnie pominąć token sesji autouzupełniania w żądaniu. Jeśli token sesji zostanie pominięty, każde żądanie będzie rozliczane osobno, co spowoduje naliczenie opłaty za kod SKU Autouzupełnianie – za żądanie. Jeśli użyjesz ponownie tokenu sesji, sesja zostanie uznana za nieprawidłową, a żądania zostaną rozliczone tak, jakby nie podano tokenu sesji.

Przykład

Gdy użytkownik wpisuje zapytanie, co kilka naciśnięć klawiszy (nie po każdym znaku) wywoływane jest żądanie autouzupełniania i zwracana jest lista możliwych wyników. Gdy użytkownik wybierze coś z listy wyników, wybór ten jest liczony jako żądanie, a wszystkie żądania wysłane podczas wyszukiwania są grupowane i liczone jako jedno żądanie. Jeśli użytkownik wybierze miejsce, zapytanie jest dostępne bezpłatnie, a opłata jest naliczana tylko za żądanie danych o miejscu. Jeśli użytkownik nie dokona wyboru w ciągu kilku minut od rozpoczęcia sesji, opłata zostanie naliczona tylko za wyszukiwane hasło.

Z perspektywy aplikacji sekwencja zdarzeń wygląda tak:

1. Użytkownik zaczyna wpisywać zapytanie, aby wyszukać „Paryż, Francja”.
2. Po wykryciu danych wejściowych użytkownika aplikacja tworzy nowy token sesji, „Token A”.
3. Gdy użytkownik wpisuje tekst, interfejs API co kilka znaków wysyła żądanie autouzupełniania, wyświetlając nową listę potencjalnych wyników dla każdego z nich:
   „P”
   „Par”
   „Paris,”
   „Paris, Fr”
   
4. Gdy użytkownik dokona wyboru:
   • Wszystkie żądania wynikające z zapytania są grupowane i dodawane do sesji reprezentowanej przez „Token A” jako jedno żądanie.
   • Wybór użytkownika jest liczony jako żądanie informacji o miejscu i dodawany do sesji reprezentowanej przez „Token A”.
5. Sesja zostaje zakończona, a aplikacja odrzuca „Token A”.

Jak rozliczane są sesje

Kompletny przykładowy kod

Ta sekcja zawiera kompletne przykłady pokazujące, jak korzystać z interfejsu Place Autocomplete Data API .

Podpowiedzi autouzupełniania miejsc

Poniższy przykład pokazuje wywołanie fetchAutocompleteSuggestions() dla danych wejściowych „Tadi”, a następnie wywołanie toPlace() dla pierwszego wyniku podpowiedzi, po którym następuje wywołanie fetchFields() w celu uzyskania szczegółowych informacji o miejscu.

TypeScript

async function init() {
    const { AutocompleteSessionToken, AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    // Add an initial request body.
    const request: google.maps.places.AutocompleteRequest = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title')!;
    title.appendChild(
        document.createTextNode(
            'Query predictions for "' + request.input + '":'
        )
    );

    const resultsElement = document.getElementById('results')!;

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');

        listItem.appendChild(
            document.createTextNode(placePrediction!.text.toString())
        );
        resultsElement.appendChild(listItem);
    }

    const place = suggestions[0].placePrediction!.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById('prediction')!;
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}

void init();
index.ts

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

JavaScript

async function init() {
    const { AutocompleteSessionToken, AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    // Add an initial request body.
    const request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title');
    title.appendChild(
        document.createTextNode(
            'Query predictions for "' + request.input + '":'
        )
    );

    const resultsElement = document.getElementById('results');

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');

        listItem.appendChild(
            document.createTextNode(placePrediction.text.toString())
        );
        resultsElement.appendChild(listItem);
    }

    const place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById('prediction');
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}

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

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Predictions</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>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>
index.html

Autouzupełnianie miejsc z wyprzedzeniem z sesjami

Ten przykład ilustruje te koncepcje:

• Wywołanie metody fetchAutocompleteSuggestions() na podstawie zapytań użytkowników i wyświetlenie w odpowiedzi listy prognozowanych miejsc.
• używanie tokenów sesji do grupowania zapytania użytkownika z ostatecznym żądaniem informacji o miejscu;
• pobieranie informacji o wybranym miejscu i wyświetlanie znacznika,
• Używanie gniazd elementów sterujących do zagnieżdżania elementów interfejsu w elemencie gmp-map.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
const titleElement = document.querySelector<HTMLElement>('.title')!;
const resultsContainerElement = document.querySelector('.results')!;
const inputElement = document.querySelector('input')!;
const tokenStatusElement = document.querySelector('.token-status')!;
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request: google.maps.places.AutocompleteRequest = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    innerMap.addListener('bounds_changed', () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent: Event) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    if (!(inputEvent.target as HTMLInputElement)?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = (inputEvent.target as HTMLInputElement).value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

    // Clear the list first.
    resultsContainerElement.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            void onPlaceSelected(placePrediction.toPlace());
        });

        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place: google.maps.places.Place) {
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } =
        await google.maps.importLibrary('places');

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

void init();
index.ts

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

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
const titleElement = document.querySelector('.title');
const resultsContainerElement = document.querySelector('.results');
const inputElement = document.querySelector('input');
const tokenStatusElement = document.querySelector('.token-status');
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    innerMap.addListener('bounds_changed', () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

    // Clear the list first.
    resultsContainerElement.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            void onPlaceSelected(placePrediction.toPlace());
        });

        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } =
        await google.maps.importLibrary('places');

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

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-button {
    height: 3rem;
    width: 100%;
    background-color: transparent;
    text-align: left;
    border: none;
    cursor: pointer;
}

.place-button:focus-visible {
    outline: 2px solid #0056b3;
    border-radius: 2px;
}

.input {
    width: 300px;
    font-size: small;
    margin-bottom: 1rem;
}

/* Styles for the floating panel */
.controls {
    background-color: #fff;
    border-radius: 8px;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
    font-family: sans-serif;
    font-size: small;
    margin: 12px;
    padding: 1rem;
}

.title {
    font-weight: bold;
    margin-top: 1rem;
    margin-bottom: 0.5rem;
}

.results {
    list-style-type: none;
    margin: 0;
    padding: 0;
}

.results li:not(:last-child) {
    border-bottom: 1px solid #ddd;
}

.results li:hover {
    background-color: #eee;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Session</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="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
            <div class="controls" slot="control-inline-start-block-start">
                <input
                    type="text"
                    class="input"
                    placeholder="Search for a place..."
                    autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
                <div class="token-status"></div>
                <div class="title"></div>
                <ol class="results"></ol>
            </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 (nowego).
• 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 wersja), użyj masek pól w widżetach informacje o miejscu (nowa wersja) i Autouzupełnianie (nowa wersja), aby zwracać tylko potrzebne pola danych Autouzupełniania (nowa wersja).

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 wybranego przez użytkownika miejsca, 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 (nowego), która odpowiada Twoim potrzebom, wybierz kartę odpowiadającą Twojej odpowiedzi na poniższe pytanie.

Czy Twoja aplikacja wymaga innych informacji niż adres i szerokość/długość geograficzna wybranej prognozy?

Tak, potrzebuję więcej informacji

Używaj autouzupełniania (nowego) opartego na sesjach z informacjami o miejscu (nowymi).
Ponieważ Twoja aplikacja wymaga informacji o miejscu (nowych), takich jak nazwa miejsca, status firmy czy 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 i iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania informacji o miejscu (nowe) dotyczące 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). Wysyłając żądanie dotyczące informacji o miejscu (nowych) dla 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).

Nie, potrzebuje tylko adresu i lokalizacji

Geocoding API może być bardziej opłacalną opcją niż informacje o miejscu (nowa wersja) w przypadku Twojej aplikacji, w zależności od wydajności Autouzupełniania (nowa wersja). 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 odpowiedzieć na poniższe pytanie, przeanalizuj, ile znaków średnio wpisuje użytkownik, zanim wybierze podpowiedź autouzupełniania (nową) w Twojej aplikacji.

Czy użytkownicy wybierają podpowiedź autouzupełniania (nową) średnio w maksymalnie 4 żądaniach?

Tak

Zaimplementuj Autouzupełnianie (nowe) automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku wybranej prognozy miejsca.
Geocoding API dostarcza adresy i 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 oczekiwanych podpowiedzi przy wpisywaniu jeszcze mniejszej liczby znaków.

Nie

Używaj autouzupełniania (nowego) opartego na sesjach z informacjami o miejscu (nowymi).
Średnia liczba żądań, które spodziewasz się wysłać, 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 informacji o miejscu (nowe) dotyczące 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). Podczas wysyłania żądania dotyczącego informacji o miejscu (nowych) na temat 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, aby aplikacja wysyłał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, to gdy 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 geokodowanie¹.

Jeśli opóźnienie żądań może obniżyć średnią liczbę żądań automatycznych 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 jako opóźnienie przez użytkownika, który może oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać oczekiwane podpowiedzi przy użyciu mniejszej liczby znaków.

---

1. Koszty znajdziesz w cennikach Google Maps Platform.

Sprawdzone metody dotyczące wydajności

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

• 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 dostosować lokalizację według widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (nowych), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć pierwotnych 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 ustawiania lokalizacji.
  Inne scenariusze, w których najlepiej jest użyć Geocoding API, to:
  • Użytkownicy wpisują adresy lokali, np. adresy konkretnych jednostek 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ący 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 zdefiniowanym 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 tylko wyniki 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.