API de Place Autocomplete Data

Desarrolladores del Espacio Económico Europeo (EEE)

La API de Place Autocomplete Data te permite recuperar predicciones de lugares de forma programática para crear experiencias de autocompletado personalizadas con un mayor grado de control que el que se puede lograr con el widget de autocompletar. En esta guía, aprenderás a usar la API de Place Autocomplete Data para realizar solicitudes de autocompletado basadas en las búsquedas de los usuarios.

En el siguiente ejemplo, se muestra una integración de escritura anticipada simplificada. Ingresa tu búsqueda, como "pizza" o "poke", y, luego, haz clic para seleccionar el resultado que quieras.

Solicitudes a Autocomplete

Una solicitud de autocompletado toma una cadena de entrada de búsqueda y devuelve una lista de predicciones de lugares. Para realizar una solicitud de autocompletado, llama a fetchAutocompleteSuggestions() y pasa una solicitud con las propiedades necesarias. La propiedad input contiene la cadena de búsqueda. En una aplicación típica, este valor se actualizaría a medida que el usuario escribe una búsqueda. La solicitud debe incluir un sessionToken, que se usa para fines de facturación.

En el siguiente fragmento, se muestra cómo crear un cuerpo de solicitud y agregar un token de sesión, y, luego, llamar a fetchAutocompleteSuggestions() para obtener una lista de objetos 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

Cómo restringir las predicciones de Autocomplete

De forma predeterminada, Place Autocomplete presenta todos los tipos de lugares, personalizados según la ubicación del usuario, y obtiene información de todos los campos de datos disponibles para el lugar que este selecciona. Configura las opciones de Place Autocomplete para presentar predicciones más relevantes mediante la restricción o personalización de los resultados.

La restricción de resultados hace que el widget de Autocomplete ignore cualquier resultado que esté fuera del área de restricción. Una práctica común es restringir los resultados a los límites del mapa. La personalización de resultados hace que el widget de Autocomplete muestre resultados dentro del área especificada, pero algunas coincidencias pueden estar fuera de esa área.

Usa la propiedad origin para especificar el punto de origen desde el cual se calculará la distancia geodésica hasta el destino. Si se omite este valor, no se devuelve la distancia.

Usa la propiedad includedPrimaryTypes para especificar hasta cinco tipos de lugares. Si no se especifican tipos, se devolverán lugares de todos los tipos.

Consulta la referencia de la API

Cómo obtener detalles de un lugar

Para devolver un objeto Place a partir del resultado de una predicción de lugar, primero llama a toPlace() y, luego, llama a fetchFields() en el objeto Place resultante (el ID de sesión de la predicción de lugar se incluye automáticamente). Llamar a fetchFields() finaliza la sesión de autocompletado. 

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

Tokens de sesión

Los tokens de sesión agrupan las fases de consulta y selección de la búsqueda con autocompletado de un usuario en una sesión discreta para realizar la facturación correspondiente. La sesión comienza cuando el usuario comienza a escribir. La sesión finaliza cuando el usuario selecciona un lugar y se realiza una llamada a Place Details.

Para crear un nuevo token de sesión y agregarlo a una solicitud, crea una instancia de AutocompleteSessionToken y, luego, establece la propiedad sessionToken de la solicitud para usar los tokens como se muestra en el siguiente fragmento: 

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

Una sesión finaliza cuando se llama a fetchFields(). Después de crear la instancia de Place, no es necesario que pases el token de sesión a fetchFields(), ya que esto se controla automáticamente. 

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

Crea un token de sesión para la próxima sesión creando una instancia nueva de AutocompleteSessionToken.

Recomendaciones sobre el token de sesión:

  • Usa tokens de sesión para todas las llamadas a Place Autocomplete.
  • Genera un token nuevo para cada sesión.
  • Pasa un token de sesión único para cada sesión nueva. Si usas el mismo token en más de una sesión, cada solicitud se facturará de forma individual.

De forma opcional, puedes omitir el token de sesión de Autocomplete en una solicitud. Si se omite el token de sesión, cada solicitud se factura por separado, lo que activa el SKU de Autocomplete - Per Request. Si vuelves a usar el token para otra sesión, esta se considera no válida y las solicitudes se cobran como si no se hubiera proporcionado un token de sesión.

Ejemplo

A medida que el usuario escribe una búsqueda, se llama a una solicitud de autocompletar cada pocos toques de teclas (no por carácter) y se devuelve una lista de posibles resultados. Cuando el usuario realiza una selección en la lista de resultados, la selección se considera una solicitud, y todas las solicitudes realizadas durante la búsqueda se agrupan y se cuentan como una sola solicitud. Si el usuario selecciona un lugar, la búsqueda está disponible sin cargo, y solo se cobra la solicitud de datos de Place. Si el usuario no realiza una selección en los primeros minutos de la sesión, solo se cobrará la búsqueda.

Desde la perspectiva de una app, el flujo de eventos es el siguiente:

  1. Un usuario comienza a escribir una búsqueda para encontrar “París, Francia”.
  2. Cuando detecta la entrada del usuario, la app crea un nuevo token de sesión, "Token A".
  3. A medida que el usuario escribe, la API realiza una solicitud de autocompletado cada pocos caracteres y muestra una nueva lista de posibles resultados para cada uno:
    "P"
    "Par"
    "París"
    "París, Francia"
  4. Cuando el usuario realiza una selección, sucede lo siguiente:
    • Todas las solicitudes resultantes de la consulta se agrupan y se agregan a la sesión representada por "Token A" como una sola solicitud.
    • La selección del usuario se contabiliza como una solicitud de Place Details y se agrega a la sesión representada por "Token A".
  5. La sesión finaliza y la app descarta el "Token A".
Obtén más información sobre cómo se facturan las sesiones

Ejemplo de código completo

En esta sección, se incluyen ejemplos completos que muestran cómo usar la API de Place Autocomplete Data .

Predicciones de Place Autocomplete

En el siguiente ejemplo, se muestra cómo llamar a fetchAutocompleteSuggestions() para la entrada "Tadi", luego llamar a toPlace() en el primer resultado de la predicción y, por último, llamar a fetchFields() para obtener detalles del lugar.

TypeScript

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

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

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

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

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

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

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

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

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

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

init();
index.ts

JavaScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    // Add an initial request body.
    let request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };
    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    const title = document.getElementById('title');
    title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":'));
    const resultsElement = document.getElementById('results');
    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        // Create a new list element.
        const listItem = document.createElement('li');
        listItem.appendChild(document.createTextNode(placePrediction.text.toString()));
        resultsElement.appendChild(listItem);
    }
    let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    const placeInfo = document.getElementById('prediction');
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}
init();
index.js

CSS

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

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

style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Predictions</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>
index.html

Prueba la muestra

Autocompletado de Place con sesiones

En este ejemplo, se muestran los siguientes conceptos:

  • Llamar a fetchAutocompleteSuggestions() en función de las búsquedas del usuario y mostrar una lista de lugares predichos en respuesta
  • Usar tokens de sesión para agrupar una búsqueda del usuario con la solicitud final de Place Details
  • Recupera los detalles del lugar seleccionado y muestra un marcador.
  • Usa la asignación de ranuras de control para anidar elementos de la IU en el elemento gmp-map.

TypeScript

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        if (!placePrediction) {
            continue;
        }

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

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

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

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

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

    await refreshToken();

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

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

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

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

    // Increment the token counter.
    tokenCount++;

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

init();
index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
let titleElement = document.querySelector('.title');
let resultsContainerElement = document.querySelector('.results');
let inputElement = document.querySelector('input');
let tokenStatusElement = document.querySelector('.token-status');
let newestRequestId = 0;
let tokenCount = 0;
// Create an initial request body.
const request = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};
async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Update request center and bounds when the map bounds change.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });
    inputElement.addEventListener('input', makeAutocompleteRequest);
}
async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;
    const { AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }
    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;
    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId)
        return;
    titleElement.innerText = `Place predictions for "${request.input}"`;
    // Clear the list first.
    resultsContainerElement.replaceChildren();
    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        if (!placePrediction) {
            continue;
        }
        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');
        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}
// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    const { AdvancedMarkerElement } = (await google.maps.importLibrary('marker'));
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';
    await refreshToken();
    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }
    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });
    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}
// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } = (await google.maps.importLibrary('places'));
    // Increment the token counter.
    tokenCount++;
    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}
init();
index.js

CSS

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

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

.place-button {
    height: 3rem;
    width: 100%;
    background-color: transparent;
    text-align: left;
    border: none;
    cursor: pointer;
}

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

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

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

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

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

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

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

style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Session</title>

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

Prueba la muestra

Optimización de Autocomplete (nuevo)

En esta sección, se describen algunas prácticas recomendadas que te ayudarán a aprovechar al máximo el servicio Autocomplete (nuevo).

A continuación, se indican algunos lineamientos generales:

  • La forma más rápida de desarrollar una interfaz de usuario funcional es usar el widget de Autocomplete (nuevo) de la API de Maps JavaScript, el widget de Autocomplete (nuevo) del SDK de Places para Android o el widget de Autocomplete (nuevo) del SDK de Places para iOS.
  • Comprende los campos de datos esenciales de Autocomplete (nuevo) desde el principio.
  • Los campos de restricción y personalización de la ubicación son opcionales, pero pueden afectar significativamente el rendimiento del autocompletado.
  • Usa el procedimiento de manejo de errores para asegurarte de que tu app administre el problema de forma adecuada si la API muestra un error.
  • Asegúrate de que tu app gestione correctamente los problemas cuando no haya selección y ofrezca a los usuarios una manera de continuar.

Prácticas recomendadas para la optimización de los costos

Optimización básica de los costos

Para optimizar el costo de usar el servicio Autocomplete (nuevo), usa máscaras de campo en los widgets de Place Details (nuevo) y Autocomplete (nuevo) para mostrar solo los campos de datos de Autocomplete (nuevo) que necesitas.

Optimización avanzada de los costos

Considera utilizar la implementación programática de Autocomplete (nuevo) para acceder a los SKU: precios de solicitudes de Autocomplete y solicitar resultados de la API de Geocoding sobre el lugar seleccionado en lugar de utilizar Place Details (nuevo). Los precios por solicitud asociados con la API de Geocoding son más rentables que los precios por sesión (basados en sesión) si se cumplen las siguientes condiciones:

  • Si solo necesitas las coordenadas de latitud y longitud, o la dirección del lugar seleccionado por el usuario, la API de Geocoding proporciona esta información de manera más fácil que una llamada a Place Details (nuevo).
  • Si los usuarios seleccionan una predicción de autocompletar con un promedio de cuatro solicitudes o menos, el precio por solicitud puede ser más rentable que el precio por sesión.
Si necesitas ayuda para elegir la implementación de Autocomplete (nuevo) que se adapte a tus necesidades, selecciona la pestaña que corresponda a tu respuesta a la siguiente pregunta.

¿Tu aplicación requiere algún dato diferente de la dirección y las coordenadas de latitud o longitud de la predicción seleccionada?

Sí, necesita más detalles

Usa Autocomplete basado en sesiones (nuevo) con Place Details (nuevo).
Dado que tu aplicación requiere Place Details (nuevo), como el nombre del lugar, el estado comercial o el horario de atención, tu implementación de Autocomplete (nuevo) debe usar un token de sesión (de forma programática o integrado en los widgets de JavaScript, Android o iOS) por sesión, además de los SKU de Places aplicables, según los campos de datos de lugares que solicites.1

Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android, o iOS. Esto incluye las solicitudes de Autocomplete (nuevo) y Place Details (nuevo) en la predicción seleccionada. Asegúrate de especificar el parámetro fields para asegurarte de solicitar únicamente los campos de datos de Autocomplete (nuevo) que necesitas.

Implementación programática
Usa un token de sesión con tus solicitudes de Autocomplete (nuevo). Cuando solicites Place Details (nuevo) sobre la predicción seleccionada, incluye los siguientes parámetros:

  1. El ID de lugar de la respuesta de Autocomplete (nuevo)
  2. Es el token de sesión que se usó en la solicitud de Autocomplete (nuevo).
  3. El parámetro fields que especifica los campos de datos de Autocomplete (nuevo) que necesitas

No, solo requiere la dirección y la ubicación

La API de Geocoding podría ser una opción más rentable que Place Details (nuevo) para tu aplicación, según el rendimiento de tu uso de Autocomplete (nuevo). La eficiencia de Autocomplete (nuevo) de cada aplicación varía según las búsquedas que ingresan los usuarios, dónde se usa la aplicación y si se siguen las prácticas recomendadas de optimización del rendimiento.

Para responder la siguiente pregunta, analiza cuántos caracteres escribe un usuario en promedio antes de seleccionar una predicción de Autocomplete (nuevo) en tu aplicación.

¿Tus usuarios seleccionan, en promedio, una predicción de Autocomplete (nuevo) cada cuatro solicitudes o menos?

Sí

Implementa Autocomplete (nuevo) de manera programática sin tokens de sesión y llama a la API de Geocoding en la predicción de lugar seleccionada.
La API de Geocoding proporciona direcciones y coordenadas de latitud y longitud. Realizar cuatro solicitudes de Autocomplete más una llamada a la API de Geocoding sobre la predicción de lugar seleccionada cuesta menos que el costo por sesión de Autocomplete (nuevo).1

Considera aplicar las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.

No

Usa Autocomplete basado en sesiones (nuevo) con Place Details (nuevo).
Dado que la cantidad promedio de solicitudes que esperas realizar antes de que un usuario seleccione una predicción de Autocomplete (nuevo) supera el costo del precio por sesión, tu implementación de Autocomplete (nuevo) debe usar un token de sesión para las solicitudes de Autocomplete (nuevo) y la solicitud asociada de Place Details (nuevo) por sesión. 1

Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android, o iOS. Esto incluye las solicitudes de Autocomplete (nuevo) y la solicitud de Place Details (nuevo) en la predicción seleccionada. Asegúrate de especificar el parámetro fields para asegurarte de solicitar únicamente los campos que necesitas.

Implementación programática
Usa un token de sesión con tus solicitudes de Autocomplete (nuevo). Cuando solicites Place Details (nuevo) sobre la predicción seleccionada, incluye los siguientes parámetros:

  1. El ID de lugar de la respuesta de Autocomplete (nuevo)
  2. Es el token de sesión que se usó en la solicitud de Autocomplete (nuevo).
  3. El parámetro fields que especifica campos como la dirección y la geometría

Considera retrasar las solicitudes de Autocomplete (nuevo)
Puedes emplear estrategias como demorar una solicitud de Autocomplete (nuevo) hasta que el usuario escriba los primeros tres o cuatro caracteres para que tu aplicación realice menos solicitudes. Por ejemplo, realizar solicitudes de Autocomplete (nuevo) para cada carácter después de que el usuario haya escrito el tercer carácter significa que, si el usuario escribe siete caracteres y, luego, selecciona una predicción para la que realizas una solicitud a la API de Geocoding, el costo total sería el de 4 solicitudes de Autocomplete (nuevo) por solicitud más Geocoding.1

Si retrasar las solicitudes puede hacer que tu solicitud programática promedio sea inferior a cuatro, puedes seguir las instrucciones para implementar Autocomplete (nuevo) con la API de Geocoding y obtener un rendimiento optimizado. Ten en cuenta que demorar las solicitudes puede percibirse como latencia por parte del usuario, que tal vez espere ver predicciones con cada letra que ingresa.

Considera seguir las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.

  1. Para conocer los costos, consulta las listas de precios de Google Maps Platform.

Prácticas recomendadas para el rendimiento

Los siguientes lineamientos describen maneras de optimizar el rendimiento de Autocomplete (nuevo):

  • Agrega restricciones por país, personalización de la ubicación y, en el caso de las implementaciones programáticas, la preferencia de idioma a la implementación de Autocomplete (nuevo). La preferencia de idioma no es necesaria para los widgets, dado que toman esta información del navegador o el dispositivo móvil del usuario.
  • Si Autocomplete (nuevo) cuenta con un mapa, puedes personalizar la ubicación según su viewport.
  • En las situaciones en que un usuario no elige una de las predicciones de Autocomplete (nuevo), generalmente, porque ninguna de ellas indica la dirección del resultado deseado, puedes reutilizar la entrada original del usuario para tratar de obtener resultados más relevantes:
    • Si esperas que el usuario ingrese solo información de la dirección, reutiliza la entrada original del usuario en una llamada a la API de Geocoding.
    • Si esperas que el usuario ingrese búsquedas para un lugar específico por nombre o dirección, usa una solicitud de Place Details (nuevo). Si se espera que los resultados pertenezcan únicamente a una región específica, usa la restricción de ubicación.
    A continuación, indicamos otras situaciones en las que es mejor recurrir a la API de Geocoding:
    • Usuarios que ingresan direcciones de subinstalaciones, como direcciones de unidades o apartamentos específicos dentro de un edificio Por ejemplo, la dirección checa "Stroupežnického 3191/17, Praha" genera una predicción parcial en Autocomplete (nuevo).
    • Usuarios que ingresan direcciones con prefijos de tramo de ruta, como "23-30 29th St, Queens" en la ciudad de Nueva York o "47-380 Kamehameha Hwy, Kaneohe" en la isla de Kauai en Hawái

Ajuste de la ubicación

Personaliza los resultados para un área específica pasando un parámetro location y un parámetro radius. Esto indica a Autocomplete (nuevo) que prefiera mostrar resultados dentro del área definida. Es posible que también se muestren resultados externos al área definida. Puedes usar el parámetro components para filtrar los resultados y mostrar solo los lugares dentro de un país especificado.

Restricción de ubicación

Restringe los resultados a un área específica pasando un parámetro locationRestriction.

También puedes restringir los resultados a la región definida por location y un parámetro radius agregando el parámetro locationRestriction. Esto indica a Autocomplete (nuevo) que muestre solo los resultados dentro de esa región.