Se usó la API de Cloud Translation para traducir esta página.

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 al destino. Si se omite este valor, no se muestra 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 token de sesión nuevo y agregarlo a una solicitud, crea una instancia de AutocompleteSessionToken y, luego, configura la propiedad sessionToken de la solicitud para que use 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 autocompletado cada pocas pulsaciones 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:

Un usuario comienza a escribir una búsqueda para encontrar “París, Francia”.
Cuando detecta la entrada del usuario, la app crea un nuevo token de sesión, "Token A".
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"
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".
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

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
    // @ts-ignore
    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 + '":'));

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

        // Create a new list element.
        const listItem = document.createElement('li');
        const resultsElement = document.getElementById("results") as HTMLElement;
        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

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
  // @ts-ignore
  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 + '":'),
  );

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    // Create a new list element.
    const listItem = document.createElement("li");
    const resultsElement = document.getElementById("results");

    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>
  </head>
  <body>
    <div id="title"></div>
    <ul id="results"></ul>
    <p><span id="prediction"></span></p>
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>index.html

Prueba la muestra

JSFiddle.net Google Cloud Shell

Escritura anticipada de Place Autocomplete con sesiones

En este ejemplo, se muestra cómo llamar a fetchAutocompleteSuggestions() en función de las búsquedas del usuario, mostrar una lista de lugares predichos en respuesta y, finalmente, recuperar los detalles del lugar seleccionado. En el ejemplo, también se muestra el uso de tokens de sesión para agrupar una búsqueda del usuario con la solicitud final de Place Details.

TypeScript

let titleElement;
let resultsContainerElement;
let inputElement;

let newestRequestId = 0;

// Add an initial request body.
const request = {
    input: '',
    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',
};

function init() {
    titleElement = document.getElementById('title');
    resultsContainerElement = document.getElementById('results');
    inputElement = document.querySelector('input');
    inputElement.addEventListener('input', makeAutocompleteRequest);
    refreshToken(request);
}

async function makeAutocompleteRequest(inputEvent) {
    // Reset elements and exit if an empty string is received.
    if (inputEvent.target.value == '') {
        titleElement.innerText = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;

    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    // Fetch autocomplete suggestions and show them in a list.
    // @ts-ignore
    const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

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

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

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

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

        // Create a link for the place, add an event handler to fetch the place.
        const a = document.createElement('a');
        a.addEventListener('click', () => {
            onPlaceSelected(placePrediction!.toPlace());
        });
        a.innerText = placePrediction!.text.toString();

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

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    const placeText = document.createTextNode(`${place.displayName}: ${place.formattedAddress}`);
    resultsContainerElement.replaceChildren(placeText);
    titleElement.innerText = 'Selected Place:';
    inputElement.value = '';
    refreshToken(request);
}

// Helper function to refresh the session token.
function refreshToken(request) {
    // Create a new session token and add it to the request.
    request.sessionToken = new google.maps.places.AutocompleteSessionToken();
}

declare global {
    interface Window {
      init: () => void;
    }
  }
  window.init = init;index.ts

JavaScript

let titleElement;
let resultsContainerElement;
let inputElement;
let newestRequestId = 0;
// Add an initial request body.
const request = {
    input: '',
    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',
};
function init() {
    titleElement = document.getElementById('title');
    resultsContainerElement = document.getElementById('results');
    inputElement = document.querySelector('input');
    inputElement.addEventListener('input', makeAutocompleteRequest);
    refreshToken(request);
}
async function makeAutocompleteRequest(inputEvent) {
    // Reset elements and exit if an empty string is received.
    if (inputEvent.target.value == '') {
        titleElement.innerText = '';
        resultsContainerElement.replaceChildren();
        return;
    }
    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;
    // Fetch autocomplete suggestions and show them in a list.
    // @ts-ignore
    const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId)
        return;
    titleElement.innerText = `Query predictions for "${request.input}"`;
    // Clear the list first.
    resultsContainerElement.replaceChildren();
    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        // Create a link for the place, add an event handler to fetch the place.
        const a = document.createElement('a');
        a.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        a.innerText = placePrediction.text.toString();
        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(a);
        resultsContainerElement.appendChild(li);
    }
}
// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    const placeText = document.createTextNode(`${place.displayName}: ${place.formattedAddress}`);
    resultsContainerElement.replaceChildren(placeText);
    titleElement.innerText = 'Selected Place:';
    inputElement.value = '';
    refreshToken(request);
}
// Helper function to refresh the session token.
function refreshToken(request) {
    // Create a new session token and add it to the request.
    request.sessionToken = new google.maps.places.AutocompleteSessionToken();
}
window.init = 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;
}

a {
  cursor: pointer;
  text-decoration: underline;
  color: blue;
}

input {
  width: 300px;
}
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>
  </head>
  <body>
    <input id="input" type="text" placeholder="Search for a place..." />
    <div id="title"></div>
    <ul id="results"></ul>
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8&callback=init&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

Prueba la muestra

JSFiddle.net

API de Place Autocomplete Data Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Solicitudes a Autocomplete

Cómo restringir las predicciones de Autocomplete

Cómo obtener detalles de un lugar

Tokens de sesión

Recomendaciones sobre el token de sesión:

Ejemplo

Ejemplo de código completo

Predicciones de Place Autocomplete

TypeScript

JavaScript

CSS

HTML

Prueba la muestra

Escritura anticipada de Place Autocomplete con sesiones

TypeScript

JavaScript

CSS

HTML

Prueba la muestra

API de Place Autocomplete Data