Разместить API данных автозаполнения

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

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

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

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

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

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

Ограничить прогнозы автозаполнения

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

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

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

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

См. справочник API.

Получить информацию о месте

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

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

Токены сессии

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

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

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

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

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

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

Рекомендации по токенам сессии:

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

При желании вы можете не указывать токен сессии для автозаполнения в запросе. Если токен сессии отсутствует, каждый запрос оплачивается отдельно, что активирует опцию « Автозаполнение — за запрос» . Если вы повторно используете токен сессии, сессия считается недействительной, и запросы оплачиваются так, как если бы токен сессии не был предоставлен.

Пример

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

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

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

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

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

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

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

Машинопись 

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

Попробуйте образец

Включите автозаполнение и автоподсказку при наличии сессий.

Этот пример демонстрирует следующие понятия:

  • Вызов функции fetchAutocompleteSuggestions() на основе запросов пользователя и отображение списка предполагаемых мест в ответ.
  • Использование токенов сессии для группировки запроса пользователя с окончательным запросом сведений о месте.
  • Получение подробных сведений о выбранном месте и отображение маркера.
  • Использование слотирования элементов управления для вложения элементов пользовательского интерфейса в элемент gmp-map .

Машинопись 

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

Попробуйте образец

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

В этом разделе описаны лучшие практики, которые помогут вам максимально эффективно использовать сервис автозаполнения (новый).

Вот несколько общих рекомендаций:

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

Передовые методы оптимизации затрат

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

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

Расширенная оптимизация затрат

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

  • Если вам нужны только широта/долгота или адрес выбранного пользователем места, API геокодирования предоставит эту информацию дешевле, чем вызов функции «Подробная информация о месте (новая)».
  • Если пользователи выбирают вариант автозаполнения в среднем не более чем в четырех запросах на автозаполнение (новое), то ценообразование за запрос может оказаться более экономически выгодным, чем ценообразование за сессию.
Чтобы получить помощь в выборе подходящей вам реализации автозаполнения (новая версия), выберите вкладку, соответствующую вашему ответу на следующий вопрос.

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

Да, требуется более подробная информация.

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

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

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

  1. Идентификатор места из ответа автозаполнения (нового).
  2. Токен сессии, используемый в запросе автозаполнения (нового запроса).
  3. Параметр fields указывает необходимые поля данных для автозаполнения (нового файла).

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

API геокодирования может оказаться более экономически выгодным вариантом, чем функция «Подробная информация о месте» (новая функция), для вашего приложения, в зависимости от производительности функции автозаполнения (новая функция). Эффективность автозаполнения (новая функция) в каждом приложении варьируется в зависимости от того, что вводят пользователи, где используется приложение и были ли внедрены лучшие практики оптимизации производительности .

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

В среднем, пользователи выбирают вариант автозаполнения (новый) в четырех или менее запросах?

Да

Реализуйте автозаполнение (новое) программным способом без использования токенов сессии и вызывайте API геокодирования для прогнозирования выбранного места.
API геокодирования предоставляет адреса и координаты широты/долготы. Выполнение четырех запросов автозаполнения плюс вызов API геокодирования для прогнозирования выбранного места обходится дешевле, чем стоимость автозаполнения (нового) за сессию. 1

Рассмотрите возможность применения лучших практик повышения производительности , чтобы помочь вашим пользователям получить желаемый результат, используя еще меньше символов.

Нет

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

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

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

  1. Идентификатор места из ответа автозаполнения (нового).
  2. Токен сессии, используемый в запросе автозаполнения (нового запроса).
  3. Параметр fields задает такие поля, как адрес и геометрия.

Рассмотрите возможность отложить запросы автозаполнения (новые).
Вы можете использовать такие стратегии, как задержка запроса автозаполнения (нового варианта) до тех пор, пока пользователь не введёт первые три или четыре символа, чтобы ваше приложение выполняло меньше запросов. Например, если запросы автозаполнения (нового варианта) выполняются для каждого символа после того, как пользователь введёт третий символ, это означает, что если пользователь введёт семь символов, а затем выберет предсказание, для которого вы выполните один запрос к API геокодирования, общая стоимость составит 4 запроса автозаполнения (нового варианта) + геокодирование. 1

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

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

  1. Информацию о стоимости можно найти в прайс-листах платформы Google Maps .

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

В следующих рекомендациях описаны способы оптимизации работы функции автозаполнения (нового кода):

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

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

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

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

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

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