Interfejs Place Autocomplete Data API

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Interfejs Place Autocomplete Data API umożliwia programowe pobieranie prognozowanych lokalizacji, aby tworzyć dostosowane funkcje autouzupełniania z większą kontrolą niż w przypadku widżetu autouzupełniania. Z tego przewodnika dowiesz się, jak korzystać z interfejsu Place Autocomplete Data API do wysyłania żądań autouzupełniania na podstawie zapytań użytkowników.

Poniższy przykład przedstawia uproszczoną integrację funkcji wpisywania z wyprzedzeniem. Wpisz zapytanie, np. „pizza” lub „poke”, a potem kliknij, aby wybrać odpowiedni wynik.

Żądania autouzupełniania

Żądanie autouzupełniania przyjmuje ciąg wejściowy zapytania i zwraca listę prognoz miejsc. Aby wysłać żądanie autouzupełniania, wywołaj funkcję fetchAutocompleteSuggestions() i przekaż żądanie z wymaganymi właściwościami. Właściwość input zawiera ciąg znaków do wyszukania. W typowym zastosowaniu ta wartość jest aktualizowana w miarę wpisywania zapytania przez użytkownika. Żądanie powinno zawierać 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.
let 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.
// @ts-ignore
request.sessionToken = token;
index.js

Ograniczanie podpowiedzi autouzupełniania

Domyślnie usługa autouzupełniania miejsc wyświetla wszystkie typy miejsc, z większym prawdopodobieństwem wyświetlania prognoz w pobliżu lokalizacji użytkownika, i pobiera wszystkie dostępne pola danych dla wybranego przez użytkownika miejsca. Ustaw opcje autouzupełniania miejsca, aby wyświetlać bardziej trafne prognozy, ograniczając lub modyfikując wyniki.

Ograniczenie wyników powoduje, że widżet autouzupełniania ignoruje wszystkie wyniki, które znajdują się poza obszarem ograniczenia. Często stosowaną praktyką jest ograniczenie wyników do granic mapy. W przypadku wyników z tendencją do odchylenia widżet autouzupełniania wyświetla wyniki w określonym obszarze, ale niektóre dopasowania mogą znajdować się poza tym obszarem.

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 określisz żadnych typów, zwracane będą miejsca wszystkich typów.

Zobacz dokumentację API

Pobieranie szczegółów miejsca

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

let 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 autouzupełniania wyszukiwania 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 wywoła wywołanie szczegółów miejsca.

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

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
// @ts-ignore
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 na potrzeby następnej sesji, tworząc nową instancję AutocompleteSessionToken.

Rekomendacje dotyczące tokena sesji:

  • Używaj tokenów sesji w przypadku wszystkich wywołań autouzupełniania miejsc.
  • Generuj nowy token dla każdej sesji.
  • W przypadku każdej nowej sesji przekaż unikalny token sesji. Używanie tego samego tokena w więcej niż 1 sesji spowoduje naliczenie opłaty za każde żądanie osobno.

Opcjonalnie możesz pominąć w żądaniu token sesji autouzupełniania. Jeśli token sesji zostanie pominięty, każde żądanie będzie rozliczane osobno, co spowoduje użycie kodu SKU Autocomplete – za żądanie. Jeśli ponownie użyjesz tokena sesji, sesja zostanie uznana za nieprawidłową, a żądania zostaną obciążone opłatą tak, jakby token sesji nie został podany.

Przykład

Gdy użytkownik wpisuje zapytanie, co kilka naciśnięć klawiszy (a nie po każdym znaku) wysyłane jest żądanie autouzupełniania i zwracana jest lista możliwych wyników. Gdy użytkownik wybierze element z listy wyników, wybór ten jest traktowany jako żądanie, a wszystkie żądania wysłane podczas wyszukiwania są łączone 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 zapytanie.

Z perspektywy aplikacji przepływ 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 i wyświetla nową listę potencjalnych wyników:
    „P”
    „Par”
    „Paryż”
    „Paryż, 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 szczegółów miejsca i dodawany do sesji reprezentowanej przez „Token A”.
  5. Sesja zostaje zakończona, a aplikacja odrzuca „Token A”.
Więcej informacji o płatnościach za 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 funkcji fetchAutocompleteSuggestions() dla danych wejściowych „Tadi”, a następnie wywołanie funkcji toPlace() na pierwszym wyniku prognozy, po którym następuje wywołanie funkcji fetchFields() w celu uzyskania szczegółów miejsca.

TypeScript

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

    // Add an initial request body.
    let 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.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

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

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

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

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

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

init();
index.ts

JavaScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    // Add an initial request body.
    let 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.
    // @ts-ignore
    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 (let 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);
    }
    let 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}`;
}
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>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</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

Wypróbuj przykład

Autouzupełnianie miejsc z sesjami

Ten przykład pokazuje te koncepcje:

  • Wywoływanie fetchAutocompleteSuggestions() na podstawie zapytań użytkowników i wyświetlanie listy przewidywanych miejsc w odpowiedzi.
  • Używanie tokenów sesji do grupowania zapytania użytkownika z ostatecznym żądaniem szczegółów miejsca.
  • Pobieranie szczegółów wybranego miejsca i wyświetlanie znacznika.
  • Używanie umieszczania elementów sterujących do zagnieżdżania elementów interfejsu w elemencie gmp-map.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let titleElement = document.querySelector('.title') as HTMLElement;
let resultsContainerElement = document.querySelector('.results') as HTMLElement;
let inputElement = document.querySelector('input') as HTMLInputElement;
let tokenStatusElement = document.querySelector('.token-status') as HTMLElement;
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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        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'
    )) as google.maps.PlacesLibrary;

    if (!inputEvent.target?.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', () => {
            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'
    )) as google.maps.MarkerLibrary;

    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'
    )) as google.maps.PlacesLibrary;

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

init();
index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
let titleElement = document.querySelector('.title');
let resultsContainerElement = document.querySelector('.results');
let inputElement = document.querySelector('input');
let 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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        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', () => {
            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}`;
}
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>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</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

Wypróbuj przykład

Optymalizacja autouzupełniania (nowość)

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

Oto kilka ogólnych wskazówek:

  • Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) w interfejsie Maps JavaScript API, widżetu autouzupełniania (nowego) w pakiecie SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) w pakiecie SDK Miejsc na iOS.
  • Poznaj najważniejsze pola danych autouzupełniania (nowość) od samego początku.
  • Pola dotyczące preferowania lokalizacji i ograniczania lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na skuteczność autouzupełniania.
  • Używaj obsługi błędów, aby zapewnić prawidłowe działanie aplikacji, gdy interfejs API zwróci błąd.
  • Sprawdź, czy aplikacja obsługuje sytuacje, w których użytkownik nie dokonał wyboru, i czy oferuje mu możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

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

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie Autocomplete (New), aby uzyskać dostęp do SKU: Autocomplete Request pricing i wysyłać zapytania o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca (nowych). Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż ceny za sesję (oparte na sesjach), jeśli spełnione są oba te warunki:

  • Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca, interfejs Geocoding API dostarczy te informacje za niższą cenę niż wywołanie interfejsu Place Details (New).
  • Jeśli użytkownicy wybierają prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognoz autouzupełniania (nowych), cena za żądanie może być bardziej opłacalna niż cena za sesję.
Aby uzyskać pomoc w wyborze implementacji Autocomplete (nowa), która odpowiada Twoim potrzebom, kliknij kartę odpowiadającą Twojej odpowiedzi na to pytanie.

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

Tak, potrzebne są dodatkowe informacje

Używaj Autouzupełniania na podstawie sesji (nowość) z informacjami o miejscu (nowość).
Ponieważ Twoja aplikacja wymaga szczegółów miejsca (nowych), takich jak nazwa miejsca, status firmy lub godziny otwarcia, w implementacji autouzupełniania (nowego) należy używać tokena sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS) na sesję oraz odpowiednich jednostek SKU Places, w zależności od tego, o które pola danych o miejscu prosisz.1

Implementacja widżetu
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania Autocomplete (New), jak i żądania Place Details (New) dotyczące wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko potrzebnych pól danych autouzupełniania (nowego).

Implementacja programowa
W żądaniach autouzupełniania (nowego) używaj tokena sesji. Gdy wysyłasz żądanie szczegółów miejsca (nowe) dotyczące wybranej prognozy, 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 danych autouzupełniania (nowego), których potrzebujesz.

Nie, wystarczy adres i lokalizacja

W zależności od skuteczności korzystania z funkcji Autocomplete (New) interfejs Geocoding API może być bardziej opłacalną opcją niż Place Details (New) w Twojej aplikacji. Skuteczność funkcji Autocomplete (New) w poszczególnych aplikacjach zależy od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji wydajności.

Aby odpowiedzieć na to pytanie, przeanalizuj, ile znaków użytkownik wpisuje średnio, zanim wybierze w aplikacji prognozę autouzupełniania (nową).

Czy użytkownicy wybierają prognozę autouzupełniania (nową) średnio w 4 lub mniejszej liczbie żądań?

Tak

Wdrażaj programowo funkcję Autocomplete (nową) bez tokenów sesji i wywołuj interfejs Geocoding API w przypadku wybranej prognozy miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wysłanie 4 żądań autouzupełniania i wywołanie interfejsu Geocoding API w przypadku wybranej podpowiedzi dotyczącej miejsca jest tańsze niż koszt autouzupełniania (nowego) na sesję.1

Rozważ zastosowanie sprawdzonych metod zwiększania wydajności, aby użytkownicy mogli uzyskać prognozę, której szukają, przy użyciu jeszcze mniejszej liczby znaków.

Nie

Używaj Autouzupełniania na podstawie sesji (nowość) z informacjami o miejscu (nowość).
Średnia liczba żądań, które prawdopodobnie wyślesz, zanim użytkownik wybierze prognozę autouzupełniania (nowego), przekracza koszt cen za sesję, więc w przypadku implementacji autouzupełniania (nowego) należy używać tokena sesji zarówno w przypadku żądań autouzupełniania (nowego), jak i powiązanego żądania szczegółów miejsca (nowego) za sesję. 1

Implementacja widżetu
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania Autocomplete (New), jak i Place Details (New) w przypadku wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko potrzebnych pól.

Implementacja programowa
W żądaniach autouzupełniania (nowego) używaj tokena sesji. Gdy wysyłasz żądanie szczegółów miejsca (nowe) dotyczące wybranej prognozy, 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ń Autocomplete (New)
Możesz zastosować strategie, takie jak opóźnienie żądania Autocomplete (New), dopóki użytkownik nie wpisze pierwszych 3–4 znaków, aby aplikacja wysyłała mniej żądań. Na przykład wysyłanie żądań autouzupełniania (nowego) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze prognozę, dla której wyślesz 1 żądanie do interfejsu Geocoding API, łączny koszt wyniesie 4 żądania autouzupełniania (nowego) + geokodowanie.1

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań programowych spadnie poniżej 4, możesz postępować zgodnie z instrukcjami dotyczącymi implementacji wydajnego interfejsu Autocomplete (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ć, że prognozy będą wyświetlane po każdym naciśnięciu klawisza.

Aby użytkownicy mogli uzyskać prognozę, której szukają, przy użyciu mniejszej liczby znaków, rozważ zastosowanie sprawdzonych metod dotyczących wydajności.

  1. Ceny znajdziesz w cennikach Google Maps Platform.

Sprawdzone metody dotyczące wydajności

Poniższe wytyczne opisują sposoby optymalizacji skuteczności autouzupełniania (nowego):

  • Dodaj do implementacji Autocomplete (New) ograniczenia dotyczące kraju, ustawienia lokalizacji i (w przypadku implementacji programowych) preferencje językowe. W przypadku widżetów nie trzeba określać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
  • Jeśli usłudze Autouzupełnianie (nowa) towarzyszy mapa, możesz określić lokalizację na podstawie widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze żadnej z podpowiedzi Autocomplete (New), zwykle dlatego, że żadna z nich nie jest szukanym adresem, możesz ponownie użyć pierwotnego tekstu wpisanego przez użytkownika, aby uzyskać bardziej trafne wyniki:
    • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
    • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania Szczegóły miejsca (nowe). Jeśli wyniki mają być wyświetlane tylko w określonym regionie, użyj ustawień lokalizacji.
    Inne scenariusze, w których warto wrócić do Geocoding API:
    • użytkownicy wpisujący adresy podrzędne, np. adresy konkretnych lokali lub mieszkań w budynku; Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściową podpowiedź w usłudze Autouzupełnianie (nowa wersja).
    • Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23–30 29th St, Queens” w Nowym Jorku lub „47–380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Preferowanie lokalizacji

Aby zawęzić wyniki do określonego obszaru, przekaż parametr location i parametr radius. To polecenie informuje usługę Autocomplete (New), że ma preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru components, aby filtrować wyniki i wyświetlać tylko miejsca w określonym kraju.

Ograniczanie lokalizacji

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

Możesz też ograniczyć wyniki do regionu zdefiniowanego przez parametr location i radius, dodając parametr locationRestriction. To polecenie informuje interfejs Autocomplete (New), że ma zwracać tylko wyniki z tego regionu.