Виджет автозаполнения мест

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

Виджет автозаполнения мест создает текстовое поле, создает в интерфейсе список с подсказками мест, которые пользователь может выбрать, а в ответ на выбор пользователя возвращает информацию о местах. Используйте виджет автозаполнения мест, чтобы встроить на веб-страницу полноценный автономный пользовательский интерфейс.

Требования

Чтобы использовать автозаполнение мест, включите Places API (новая версия) в проекте Google Cloud. Подробности – в статье Начало работы.

Что нового

Автозаполнение мест было улучшено следующим образом:

  • Интерфейс виджета Autocomplete поддерживает региональную локализацию (в том числе языки с написанием справа налево) для плейсхолдера ввода текста, логотипа списка подсказок, а также отображаемых подсказок.
  • Расширенные специальные возможности, в том числе поддержка программ чтения с экрана и взаимодействие с помощью клавиатуры.
  • Виджет Autocomplete возвращает новый класс Place, который помогает упростить обработку возвращаемого объекта.
  • Улучшенная поддержка мобильных устройств и небольших экранов.
  • Повышенная производительность и усовершенствованный визуальный дизайн.

Добавление виджета Autocomplete

Он создает на веб-странице текстовое поле, создает в интерфейсе список с подсказками мест, которые пользователь может выбрать, а в ответ на клик пользователя (определяется с помощью прослушивателя gmp-select) возвращает данные о выбранном месте. В этом разделе показано, как добавить виджет Autocomplete на веб-страницу или карту Google.

Как добавить виджет Autocomplete на веб-страницу

Чтобы добавить виджет Autocomplete на веб-страницу, создайте элемент google.maps.places.PlaceAutocompleteElement и добавьте его на страницу, как показано в примере ниже:

TypeScript

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

JavaScript

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

Ознакомьтесь полным примером кода.

Как добавить виджет Autocomplete на карту

Если ваш платежный адрес находится за пределами Европейской экономической зоны (ЕЭЗ), вы также можете использовать виджет автозаполнения с картой Google.

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

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

Затем в HTML-коде вложите новый элемент gmp-place-autocomplete в элемент div, а элемент div – в элемент gmp-map, как показано в следующем примере:

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

Чтобы добавить виджет Autocomplete на карту программно, создайте экземпляр google.maps.places.PlaceAutocompleteElement, добавьте PlaceAutocompleteElement в div и примените атрибут slot к placeAutocompleteElement, как показано в примере ниже: 

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

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

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

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

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

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

Ознакомьтесь полным примером кода.

Как добавить текст-плейсхолдер

Чтобы добавить текст плейсхолдера, используйте свойство placeholder. В примере ниже показано, как задать текст плейсхолдера в HTML:

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

Вы также можете задать текст-плейсхолдер программно:

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

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

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

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

Если границы или область просмотра не указаны, API будет определять местоположение пользователя по IP-адресу и предлагать места, расположенные поблизости. По возможности задавайте границы. В противном случае подсказки для разных пользователей могут быть неодинаковы. Также, чтобы улучшить подсказки в целом, следует выбрать подходящую область просмотра, например такую, которая устанавливается при панорамировании или масштабировании карты или задается разработчиком с учетом местоположения устройства и радиуса. Если радиус неизвестен, подходящим значением по умолчанию для автозаполнения мест считается 5 км. Не используйте следующие области просмотра: с нулевым радиусом (точку); маленького размера (менее 100 м); охватывающую весь мир.

Как ограничить поиск мест определенными странами

Чтобы ограничить поиск мест одной или несколькими странами, с помощью свойства includedRegionCodes укажите коды стран, как показано в следующем примере кода (предполагается, что вы уже создали экземпляр с именем placeAutocomplete):

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

Как ограничить поиск мест границами карты

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

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

Чтобы свойство locationRestriction не применялось, присвойте ему значение null.

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

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

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

Чтобы свойство locationBias не применялось, присвойте ему значение null.

Как ограничить результаты поиска мест определенными типами

Вы можете ограничить результаты поиска мест определенными типами мест. Для этого в свойстве includedPrimaryTypes нужно указать один или несколько типов, как показано в следующем примере:

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

Полный список поддерживаемых типов можно найти в таблицах А и Б.

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

Чтобы получить сведения о выбранном месте, добавьте прослушиватель gmp-select в экземпляр PlaceAutocompleteElement, как показано в следующем примере:

TypeScript

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

JavaScript

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

Ознакомьтесь полным примером кода.

В примере выше прослушиватель событий возвращает объект класса Place. Вызовите place.fetchFields(), чтобы получить необходимые для вашего приложения поля данных Place Details.

Прослушиватель в примере ниже запрашивает информацию о месте и показывает ее на карте.

TypeScript

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

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

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

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

JavaScript

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

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

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

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

Ознакомьтесь полным примером кода.

Примеры карт

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

Элемент Autocomplete

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

TypeScript

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

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

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

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

void init();

JavaScript

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

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

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

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

void init();

CSS

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

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

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

HTML

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

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

Карта с виджетом Autocomplete

В этом примере показано, как добавить виджет Autocomplete на карту Google.

TypeScript

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

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

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

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

    infoWindow = new InfoWindow();

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

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

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

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

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

void init();

JavaScript

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

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

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

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

    infoWindow = new InfoWindow();

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

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

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

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

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

void init();

CSS

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

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

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

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

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

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

HTML

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

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

Оптимизация функции автозаполнения (новая версия)

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

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

  • Чтобы быстро разработать пользовательский интерфейс, используйте виджет 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 Request и запрашивать результаты Geocoding API о выбранном месте вместо информации о местах (New). Тариф Per Request в сочетании Geocoding API будет выгоднее, чем тариф Per Session (на основе сеансов), если соблюдаются два следующих условия:

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

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

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

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

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

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

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

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

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

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

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

Да

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

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

Нет

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

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

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

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

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

Если при откладывании запросов среднее число программных запросов станет меньше четырех, вы сможете эффективно использовать сервис 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" новая функция автозаполнения покажет частичную подсказку.
    • Пользователь вводит адрес с префиксом для ряда домов, например "23-30 29th St, Queens" в Нью-Йорке или "47-380 Kamehameha Hwy, Kaneohe" на острове Кауаи (Гавайи).

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

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

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

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

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