Place Autocomplete Data API

Разработчики из Европейской экономической зоны (ЕЭЗ)

Place Autocomplete Data API позволяет программно получать подсказки мест, чтобы создавать персонализированные функции автозаполнения мест с более точным контролем, чем при использовании виджета автозаполнения. В этом руководстве вы узнаете, как использовать Place Autocomplete Data API для выполнения запросов автозаполнения мест на основе запросов пользователей.

Ниже приведен пример упрощенной интеграции автозаполнения. Введите поисковый запрос, например "пицца" или "поке", и выберите нужный результат.

Запросы автозаполнения

Запрос автозаполнения принимает входную строку запроса и возвращает список подсказок мест. Чтобы выполнить запрос автозаполнения, вызовите метод fetchAutocompleteSuggestions() и передайте запрос с нужными свойствами. Свойство input содержит строку для поиска. В типичном приложении это значение обновляется по мере того, как пользователь вводит запрос. Запрос должен содержать параметр sessionToken, который используется для выставления счетов.

В следующем фрагменте кода показано, как создать тело запроса, добавить токен сеанса и вызвать fetchAutocompleteSuggestions(), чтобы получить список объектов 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;

Как ограничить подсказки функции Autocomplete

По умолчанию Place Autocomplete может предлагать любые типы мест, отдавая предпочтение тем, что находятся ближе к пользователю, и получает все доступные поля данных для выбранного пользователем места. Однако вы можете задать предпочтения и ограничения, чтобы результаты лучше подходили для вашего приложения.

В таком случае виджет Autocomplete будет игнорировать те результаты, которые не входят в определенную область. Довольно распространенная практика – ограничивать результаты границами карты. Если вы зададите предпочтения таким образом, виджет Autocomplete будет показывать результаты только в заданной области, даже когда совпадения есть и за ее пределами.

Используйте свойство origin, чтобы указать начальную точку, от которой будет рассчитываться геодезическое расстояние до пункта назначения. Если это значение не указано, расстояние не возвращается.

С помощью свойства includedPrimaryTypes можно указать до пяти типов мест. Если типы не указаны, будут возвращены места всех типов.

Посмотреть документацию по API

Как получить сведения о месте

Чтобы получить объект Place из результата подсказки места, сначала вызовите toPlace(), а затем – fetchFields() для полученного объекта Place (идентификатор сеанса из подсказки места будет включен автоматически). Вызов fetchFields() завершает сеанс автозаполнения. 

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

Токены сеансов

Токены сеансов группируют этапы запроса и выбора выполняемого пользователем поиска с функцией автозаполнения в отдельный сеанс для выставления счетов. Сеанс начинается, когда пользователь начинает вводить запрос. Сеанс завершается, когда пользователь выбирает место и выполняется вызов информации о местах.

Чтобы создать токен сеанса и добавить его в запрос, создайте экземпляр AutocompleteSessionToken, а затем задайте свойство sessionToken запроса, чтобы использовать токены, как показано в следующем фрагменте кода: 

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

Сеанс завершается при вызове fetchFields(). После создания экземпляра Place вам не нужно передавать токен сеанса в fetchFields(), так как это выполняется автоматически. 

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

Создайте токен сеанса для следующего сеанса, создав новый экземпляр AutocompleteSessionToken.

Рекомендации по использованию токенов сеансов:

  • Используйте токены сеансов для всех вызовов автозаполнения мест.
  • Создавайте новый токен для каждого сеанса.
  • Передавайте уникальный токен сеанса для каждого нового сеанса. Если использовать один токен для нескольких сеансов, плата за каждый сеанс будет начислена по отдельности.

Токен сеанса автозаполнения можно не указывать в запросе. Если токен сеанса не указан, каждый запрос оплачивается отдельно по коду Autocomplete – Per Request. Если вы используете токен сеанса повторно, такой сеанс будет считаться недействительным и оплата за запросы в нем будет взиматься так, как если бы токен сеанса не был предоставлен.

Пример

Когда пользователь вводит запрос, запрос автозаполнения вызывается через каждые несколько нажатий клавиш (не для каждого символа), и возвращается список возможных результатов. Когда пользователь выбирает место из списка результатов, этот выбор считается запросом, а все запросы, сделанные во время поиска, объединяются и считаются одним запросом. Если пользователь выбирает место, поисковый запрос предоставляется бесплатно, а оплачивается только запрос данных о месте. Если пользователь не сделает выбор в течение нескольких минут после начала сеанса, плата будет взиматься только за поисковый запрос.

С точки зрения приложения последовательность событий выглядит следующим образом:

  1. Пользователь начинает вводить запрос "Париж, Франция".
  2. При обнаружении ввода данных пользователем приложение создает новый токен сеанса – "Токен А".
  3. По мере ввода API отправляет запрос на автозаполнение через каждые несколько символов, отображая новый список возможных результатов для каждого из них:
    "P"
    "Par"
    "Paris,"
    "Paris, Fr"
  4. Когда пользователь делает выбор:
    • Все запросы, полученные в результате запроса, группируются и добавляются в сеанс, представленный токеном A, как один запрос.
    • Выбор пользователя учитывается как запрос информации о местах и добавляется в сеанс, представленный токеном A.
  5. Сеанс завершается, и приложение удаляет токен А.
Подробнее о том, как оплачиваются сеансы…

Полный пример кода

В этом разделе приведены полные примеры использования Place Autocomplete Data API .

Подсказки автозаполнения мест

В примере ниже показан вызов fetchAutocompleteSuggestions() для входных данных "Tadi", затем вызов toPlace() для первого результата подсказки и вызов fetchFields() для получения информации о местах.

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

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

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

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>

Автозаполнение мест с сеансами

В этом примере показано следующее:

  • Вызов fetchAutocompleteSuggestions() на основе запросов пользователей и показ списка подсказок мест в ответ.
  • Использование токенов сеансов для группировки запроса пользователя с окончательным запросом информации о местах.
  • Получение информации о выбранном месте и показ маркера.
  • Использование слотов для вложения элементов интерфейса в элемент 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();

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

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

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>

Оптимизация Autocomplete (New)

В этом разделе приведены рекомендации по эффективному использованию сервиса Autocomplete (New).

Рассмотрим некоторые общие рекомендации.

  • Чтобы быстро разработать пользовательский интерфейс, используйте виджет Autocomplete (New) Maps JavaScript API, виджет Autocomplete (New) Places SDK для Android или виджет Autocomplete (New) Places SDK для iOS.
  • В первую очередь ознакомьтесь с самыми важными полями данных Autocomplete (New).
  • Поля с предпочтениями и ограничениями местоположений использовать не обязательно, но они могут значительно повлиять на производительность функции автозаполнения.
  • Используйте обработку ошибок в приложении на случай, если API вернет ошибку.
  • Убедитесь, что приложение сможет обработать тот случай, если пользователь не выберет место, и предложить вариант продолжения работы.

Рекомендации по оптимизации затрат

Базовая оптимизация затрат

Для оптимизации затрат на сервис Autocomplete (New) используйте маски полей в виджетах «Информация о местах» (New) и Autocomplete (New), чтобы они возвращали только нужные вам поля данных Autocomplete (New).

Дополнительная оптимизация затрат

Рассмотрите возможность программно реализовать сервис Autocomplete (New), чтобы получить доступ к тарифу SKU: Autocomplete Request и запрашивать результаты Geocoding API о выбранном месте вместо информации о местах (New). Тариф Per Request в сочетании Geocoding API будет выгоднее, чем тариф Per Session (на основе сеансов), если соблюдаются два следующих условия:

  • Если вам нужны только широта и долгота или адрес выбранного пользователем места, получить эту информацию с помощью Geocoding API дешевле, чем вызывать Place Details (New).
  • Если пользователи выбирают подсказку функции автозаполнения в среднем из первых четырех запросов подсказок Autocomplete (New) или из меньшего числа, тариф Per Request может быть выгоднее, чем Per Session.
Чтобы получить помощь в выборе подходящей реализации Autocomplete (New), нажмите на вкладку, которая соответствует вашему ответу на приведенный ниже вопрос.

Требуется ли в вашем приложении какая-либо информация помимо адреса и широты и долготы выбранной подсказки?

Да, нужно больше сведений

Используйте сервис Autocomplete (New) на основе сеансов совместно с информацией о местах (New).
Поскольку вашему приложению требуется информация о местах (новая), например название места, статус компании или часы работы, в вашей реализации Autocomplete (New) должен использоваться токен сеанса (программно или встроенный в виджеты JavaScript, Android или iOS) для каждого сеанса, а также соответствующие коды Places в зависимости от того, какие поля данных о местах вы запрашиваете.1

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android и iOS. В нее входят как запросы Autocomplete (New), так и запрос информации о местах (New) для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля данных Autocomplete (New).

Программная реализация
Используйте токен сеанса с запросами Autocomplete (New). При запросе информации о местах (New) по выбранной подсказке укажите следующие параметры:

  1. идентификатор места из ответа Autocomplete (New);
  2. токен сеанса, использованный в запросе Autocomplete (New);
  3. Параметр fields, указывающий нужные поля данных Autocomplete (New).

Нет, нужны только адрес и местоположение

Возможно, для вашего приложения Geocoding API будет более выгодным вариантом, чем информация о местах (New). Это зависит от того, насколько эффективно вы используете Autocomplete (New). Эффективность функции автозаполнения (новый вариант) в каждом приложении зависит от того, какие запросы вводят пользователи, где используется приложение и реализованы ли рекомендации по оптимизации производительности.

Чтобы ответить на приведенный ниже вопрос, проанализируйте, сколько символов в среднем вводит пользователь, прежде чем выбирать подсказку Autocomplete (New) в приложении.

Выбирают ли пользователи подсказку Autocomplete (New) в среднем из числа первых четырех запросов?

Да

Реализуйте Autocomplete (New) программно без токенов сеансов и вызывайте Geocoding API для выбранной подсказки места.
Geocoding API предоставляет адреса и координаты широты и долготы. Четыре запроса Autocomplete Requests вместе с вызовом Geocoding API о выбранной подсказке места будут стоить меньше, чем один сеанс Autocomplete (New)1.

Вы можете применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные подсказки, вводя минимальное количество символов.

Нет

Используйте сервис Autocomplete (New) на основе сеансов совместно с информацией о местах (New).
Поскольку среднее количество запросов, которые вы ожидаете сделать до того, как пользователь выберет подсказку Autocomplete (New), превышает стоимость тарифа за сеанс, в вашей реализации Autocomplete (New) должен использоваться токен сеанса как для запросов Autocomplete (New), так и для связанного запроса информации о местах (New) за сеанс. 1

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android и iOS. В нее входят как запросы Autocomplete (New), так и запрос информации о местах (New) для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля.

Программная реализация
Используйте токен сеанса с запросами Autocomplete (New). При запросе информации о местах (New) по выбранной подсказке включите следующие параметры:

  1. идентификатор места из ответа Autocomplete (New);
  2. токен сеанса, использованный в запросе Autocomplete (New);
  3. Параметр fields, указывающий поля, например адрес и геометрические данные.

Рассмотрите возможность откладывать запросы Autocomplete (New)
Вы можете попробовать различные стратегии, например откладывать запрос Autocomplete (New), пока пользователь не введет первые три или четыре символа, чтобы ваше приложение совершало меньше запросов. Например, если вы отправляете запросы Autocomplete (New) для каждого символа после того, как пользователь ввел третий символ, то, если пользователь введет семь символов и выберет подсказку, для которой вы отправите один запрос Geocoding API, общая стоимость будет равна стоимости четырех запросов Autocomplete (New) Per Request и одного запроса Geocoding API1.

Если при откладывании запросов среднее число программных запросов станет меньше четырех, вы сможете эффективно использовать сервис Autocomplete (New) с Geocoding API. Обратите внимание, что пользователь, ожидающий появления подсказок с каждым введенным символом, может принять откладывание запросов за задержку.

Вы можете применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные подсказки, вводя меньше символов.

  1. Цены указаны в прейскурантах платформы Google Карт.

Рекомендации по повышению эффективности

В рекомендациях ниже описаны способы оптимизации производительности Autocomplete (New):

  • Добавьте в свою реализацию Autocomplete (New) ограничения для отдельных стран, смещение местоположения и (для автоматизированных реализаций) языковые настройки. Предпочитаемый язык не нужен в случае виджетов, потому что для них язык определяется на основе языковых настроек браузера или мобильного устройства.
  • Если вместе с Autocomplete (New) отображается карта, вы можете сделать предпочитаемым местоположением видимую область карты.
  • Если пользователь не выберет ни одну из подсказок Autocomplete (New) – чаще всего такое бывает, если ни одна из них не соответствует искомому адресу, — вы можете повторно использовать изначально введенные пользователем данные, чтобы получить более подходящие результаты:
    • Если вы рассчитываете, что пользователь будет вводить только информацию об адресе, повторно используйте изначально введенные им данные в вызове Geocoding API.
    • Если пользователь скорее всего будет вводить запросы для определенного места по названию или адресу, используйте запрос информации о местах (New). Если ожидается, что результаты будут из определенного региона, используйте предпочтение местоположений.
    К другим сценариям, при которых лучше вернуться к использованию Geocoding API, относятся следующие:
    • Пользователи, которые вводят адреса с указанием номера квартиры или офиса. Так, для адреса в Чехии "Stroupežnického 3191/17, Praha" Autocomplete (New) покажет частичную подсказку.
    • Пользователь вводит адрес с префиксом для ряда домов, например "23-30 29th St, Queens" в Нью-Йорке или "47-380 Kamehameha Hwy, Kaneohe" на острове Кауаи (Гавайи).

Смещение местоположения

Настроить предпочтение результатов из определенной области с помощью параметров location и radius. Это указывает Autocomplete (New), что результаты в пределах заданной области нужно показывать в первую очередь. однако более отдаленные точки также могут быть включены в ответ. Вы можете использовать параметр includedRegionCodes, чтобы отфильтровать результаты и показать только места в указанной стране.

Ограничение местоположений

Ограничить результаты определенной областью, передав параметр locationRestriction.

Вы также можете ограничить результаты регионом, заданным параметрами location и radius, добавив параметр locationRestriction. В этом случае Autocomplete (New) будет возвращать результаты только в пределах этого региона.