Biblioteca de Places

Descripción general

Las funciones de la biblioteca de Places de la API de Maps JavaScript permiten que tu aplicación busque lugares (definidos en esta API como establecimientos, ubicaciones geográficas o lugares de interés destacados) dentro de un área definida, como los límites de un mapa o el área en torno a un punto fijo.

La API de Places ofrece una función de autocompletado que puedes usar para dar a tus aplicaciones el comportamiento de escritura anticipada del campo de búsqueda de Google Maps. Cuando un usuario comienza a escribir una dirección, la función de autocompletado termina la tarea. Para obtener más información, consulta la documentación sobre el autocompletado.

Cómo comenzar

Si no tienes conocimiento sobre la API de Maps JavaScript o JavaScript, te recomendamos que revises JavaScript y que obtengas una clave de API antes de comenzar.

Habilita las APIs

Antes de usar la biblioteca de Places en la API de Maps JavaScript, asegúrate de que la API de Places esté habilitada en la consola de Google Cloud, en el mismo proyecto que configuraste para la API de Maps JavaScript.

Para ver tu lista de APIs habilitadas, haz lo siguiente:

  1. Ve a la consola de Google Cloud.
  2. Haz clic en el botón Seleccionar un proyecto, selecciona el mismo proyecto que configuraste para la API de Maps JavaScript y haz clic en Abrir.
  3. En la lista de APIs del Panel, busca API de Places.
  4. Si la API de Places aparece en la lista, significa que ya está habilitada. Si la API no figura en la lista, debes habilitarla:
    1. En la parte superior de la página, selecciona HABILITAR APIS Y SERVICIOS para abrir la pestaña Biblioteca. También puedes seleccionar Biblioteca en el menú lateral izquierdo.
    2. Busca la opción API de Places y selecciónala en la lista de resultados.
    3. Selecciona HABILITAR. Cuando finalice el proceso, aparecerá la opción API de Places en la lista de APIs del Panel.

Cómo cargar la biblioteca

El servicio Places es una biblioteca independiente, separada del código principal de la API de Maps JavaScript. Para usar la funcionalidad contenida en esta biblioteca, primero debes cargarla con el parámetro libraries en la URL de arranque de la API de Google Maps:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Consulta la Descripción general de bibliotecas para obtener más información.

Agrega la API de Places a la lista de restricciones de APIs de la clave de API

Aplicar restricciones de APIs a tus claves limita el uso de la clave de API a uno o más SDKs o APIs. Las solicitudes que se realicen a una API o a un SDK asociados a la clave de API se procesarán correctamente. Las solicitudes que se realicen a una API o a un SDK no asociados con dicha clave no se podrán completar. Para restringir una clave de API y utilizarla con la biblioteca de Places de la API de Maps JavaScript, haz lo siguiente:
  1. Ve a la consola de Google Cloud.
  2. Haz clic en el menú desplegable del proyecto y selecciona aquel que contenga la clave de API que deseas proteger.
  3. Haz clic en el botón de menú y selecciona Google Maps Platform > Credenciales.
  4. En la página Credenciales, haz clic en el nombre de la clave de API que deseas proteger.
  5. En la página Restringir y cambiar nombre de la clave de API, establece las restricciones:
    • Restricciones de APIs
      • Selecciona Restringir clave.
      • Haz clic en la opción para seleccionar las APIs y selecciona API de Maps JavaScript y API de Places.
        (Si alguna de las APIs no aparece en la lista, deberás habilitarla).
  6. Haz clic en GUARDAR.

Límites y políticas de uso

Cuotas

La biblioteca de Places comparte una cuota de uso con la API de Places, como se indica en la documentación de límites de uso de la API de Places.

Políticas

El uso de la Biblioteca de Places de la API de Maps JavaScript, debe cumplir con las políticas que se describen para la API de Places.

Búsquedas de lugares

Con el servicio Places, puedes realizar los siguientes tipos de búsquedas:

La información que se devuelve puede incluir establecimientos (como restaurantes, tiendas y oficinas), así como resultados de códigos geográficos, los cuales indican direcciones, áreas políticas como pueblos y ciudades, y otros lugares de interés.

Solicitudes de Find Place

Una solicitud de Find Place te permite buscar un lugar mediante una consulta textual o un número de teléfono. Existen dos tipos de solicitudes de Find Place:

Find Place a partir de una consulta

Find Place a partir de una búsqueda toma una entrada de texto y devuelve un lugar como resultado. La entrada puede ser cualquier tipo de dato de lugar, como el nombre o la dirección de una empresa. Para realizar una solicitud de Find Place a partir de una búsqueda, llama al método findPlaceFromQuery() de PlacesService, que considera los siguientes parámetros:

  • query (obligatorio): Es la cadena de texto en la que se busca, por ejemplo, "restaurante" o "calle principal 123". Debe ser el nombre de un lugar, una dirección o una categoría de establecimientos. Cualquier otro tipo de entrada puede generar errores o resultados no válidos. La API de Places devolverá posibles coincidencias en función de esta cadena y ordenará los resultados según la relevancia percibida.
  • fields (obligatorio): Uno o más campos que especifican los tipos de datos de lugar que se devolverán.
  • locationBias (opcional): Coordenadas que definen las áreas en las que se realizará la búsqueda. Permite establecer alguno de los siguientes:
    • Un conjunto de coordenadas de latitud y longitud especificadas como LatLngLiteral, o bien como un objeto LatLng
    • Límites rectangulares (dos pares de coordenadas de latitud y longitud o un objeto LatLngBounds)
    • Radio (en metros) centrado en un conjunto de coordenadas de latitud y longitud

También debes pasar un método de devolución de llamada a findPlaceFromQuery() para controlar el objeto de resultado y la respuesta de google.maps.places.PlacesServiceStatus.

En el siguiente ejemplo, se muestra una llamada a findPlaceFromQuery() en la que se busca "Museum of Contemporary Art Australia" (Museo de Arte Contemporáneo de Australia), y se incluyen los campos name y geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 Ver ejemplo

Find Place a partir de un número de teléfono

Find Place a partir de un número de teléfono toma un número de teléfono y devuelve un lugar como resultado. Para realizar una solicitud de Finde Place a partir de un número de teléfono, llama al método findPlaceFromPhoneNumber() de PlacesService, que toma los siguientes parámetros:

  • phoneNumber (obligatorio): Es un número de teléfono en formato E.164.
  • fields (obligatorio): Uno o más campos que especifican los tipos de datos de lugar que se devolverán.
  • locationBias (opcional): Coordenadas que definen el área en la que se buscará. Puede ser uno de los siguientes tipos de información:
    • Un conjunto de coordenadas de latitud y longitud especificadas como LatLngLiteral, o bien como un objeto LatLng
    • Límites rectangulares (cuatro puntos de latitud y longitud o un objeto LatLngBounds)
    • Radio (en metros) centrado en un conjunto de coordenadas de latitud y longitud

También debes pasar un método de devolución de llamada a findPlaceFromPhoneNumber() para controlar el objeto de resultado y la respuesta de google.maps.places.PlacesServiceStatus.

Campos (métodos de Find Place)

Usa el parámetro fields para especificar un array de los tipos de datos de lugar que deseas que se muestren. Por ejemplo: fields: ['formatted_address', 'opening_hours', 'geometry']. Usa un punto para especificar valores compuestos. Por ejemplo: opening_hours.weekday_text.

Los campos corresponden a los resultados de Place Search y se dividen en tres categorías de facturación: Basic, Contact y Atmosphere. Los campos de la tarifa Basic se facturan con la tarifa base y no generan cargos adicionales. Los campos de las tarifas Contact y Atmosphere se facturan con una tarifa más alta. Consulta la hoja de precios para obtener más información. Las atribuciones (html_attributions) se muestran siempre con todas las llamadas, independientemente de si se solicitó el campo.

Basic

La categoría Basic incluye los siguientes campos:
business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color, name, permanently_closed (obsoleto), photos, place_id, plus_code y types.

Contact

La categoría Contact incluye el siguiente campo:opening_hours
(obsoleto en la Biblioteca de Places, en la API de Maps JavaScript. Usa una solicitud de Place Details para obtener los resultados de opening_hours).

Atmosphere

La categoría Atmosphere incluye los siguientes campos: price_level, rating y user_ratings_total.

Los métodos findPlaceFromQuery() y findPlaceFromPhoneNumber() toman el mismo conjunto de campos y pueden mostrar los mismos campos en sus respectivas respuestas.

Cómo establecer una personalización de ubicación (métodos de Find Place)

Usa el parámetro locationBias para que Find Place favorezca los resultados de un área en particular. Puedes configurar locationBias de las siguientes maneras:

Personaliza los resultados según un área específica:

locationBias: {lat: 37.402105, lng: -122.081974}

Define un área rectangular para realizar la búsqueda:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

También puedes usar LatLngBounds.

Define un radio (en metros) de búsqueda centrado en un área en particular:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Solicitudes de Nearby Search

Una solicitud de Nearby Search te permite buscar sitios de un área específica a través de palabras claves o tipos. En una búsqueda de este tipo, debes incluir siempre una ubicación, la cual puede especificarse con uno de estos dos métodos:

  • un objeto LatLngBounds
  • un área circular definida como la combinación de la propiedad location (que especifica el centro del círculo como un objeto LatLng) y un radio, medido en metros

Se inicia una Búsqueda de lugares cercanos de Places con una llamada al método nearbySearch() de PlacesService, el cual muestra un array de objetos PlaceResult. Ten en cuenta que el método nearbySearch() reemplaza al método search() a partir de la versión 3.9.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

Este método toma una solicitud con los siguientes campos:

  • Cualquiera de los siguientes:
    • bounds, que debe ser un objeto google.maps.LatLngBounds que defina el área de búsqueda rectangular. La distancia diagonal máxima admitida para el área de límites es de aproximadamente 100,000 metros.
    • location y radius: El primero toma un objeto google.maps.LatLng y el segundo toma un número entero, que representa el radio del círculo en metros. El radio máximo permitido es de 50,000 metros. Ten en cuenta que, cuando rankBy se configura como DISTANCE, debes especificar una location, pero no puedes especificar un radius o bounds.
  • keyword (opcional): Es un término para el que se buscarán coincidencias con todos los campos disponibles, incluidos, sin limitaciones, el nombre, el tipo y la dirección, así como las opiniones de los clientes y otro contenido de terceros.
  • minPriceLevel y maxPriceLevel (opcional): Restringe los resultados a los lugares dentro del rango especificado. El rango de valores válidos se extiende de 0 (más asequible) a 4 (más costoso), inclusive.
  • name (obsoleto): Equivale a keyword. Los valores de este campo se combinan con los del campo keyword y se pasan como parte de la misma string de búsqueda.
  • openNow (opcional): Es un valor booleano que indica que el servicio de Places solo debe mostrar los lugares que están abiertos en el momento en que se envía la consulta. Los lugares que no especifican los horarios de atención en la base de datos de Google Places no se mostrarán si incluyes este parámetro en la consulta. Establecer openNow en false no tiene ningún efecto.
  • rankBy (opcional): Especifica el orden en el que se muestran los resultados. Los posibles valores son los siguientes:
    • google.maps.places.RankBy.PROMINENCE (predeterminado): Esta opción ordena los resultados según su importancia. La clasificación da prioridad a los lugares más relevantes dentro del radio establecido sobre los lugares cercanos que coinciden con la búsqueda pero son menos relevantes. La relevancia puede verse afectada por la clasificación de un lugar en el índice de Google, la popularidad global y otros factores. Cuando se especifica google.maps.places.RankBy.PROMINENCE, el parámetro radius es obligatorio.
    • google.maps.places.RankBy.DISTANCE: Esta opción ordena los resultados en orden ascendente según su distancia desde la location especificada (obligatorio). Ten en cuenta que no puedes especificar bounds o radius personalizados si especificas RankBy.DISTANCE. Cuando especificas RankBy.DISTANCE, se requieren uno o más objetos keyword, name o type.
  • type: Restringe los resultados a los lugares que coinciden con el tipo especificado. Solo se puede especificar un tipo (si se proporciona más de un tipo, se ignoran todos los siguientes a la primera entrada). Consulta la lista de tipos admitidos.

También debes pasar un método de devolución de llamada a nearbySearch() para controlar el objeto de resultados y la respuesta google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

Ver ejemplo

Solicitudes de Text Search

Text Search de Google Places es un servicio web que devuelve información sobre un conjunto de lugares en función de una cadena; por ejemplo, "pizza en Nueva York" o "tiendas de zapatos cerca de Ottawa". El servicio responde con una lista de lugares que coinciden con la cadena de texto y con cualquier personalización de ubicación que se haya establecido. En la respuesta de búsqueda se incluye una lista de lugares. Puedes realizar una solicitud de Place Details para obtener más información sobre cualquiera de los lugares de la respuesta.

Las búsquedas de texto se inician con una llamada al método textSearch() de PlacesService. 

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

Este método toma una solicitud con los siguientes campos:

  • query (obligatorio): Es la cadena de texto en la que se basa la búsqueda, por ejemplo, "restaurante" o "calle principal 123". Debe ser un nombre de lugar, una dirección o una categoría de establecimientos. Cualquier otro tipo de entrada puede generar errores o resultados no válidos. El servicio Places devolverá posibles coincidencias en función de esta cadena y ordenará los resultados según la relevancia percibida. Este parámetro es opcional si también se usa el parámetro type en la solicitud de búsqueda.
  • Alternativa:
    • openNow: Es un valor booleano que indica que el servicio Places solo debe mostrar los lugares que están abiertos en el momento en que se envía la consulta. Los lugares que no especifican los horarios de atención en la base de datos de Google Places no se mostrarán si incluyes este parámetro en tu consulta. Establecer openNow en false no tiene ningún efecto.
    • minPriceLevel y maxPriceLevel: Restringen los resultados a los lugares que se encuentran dentro del nivel de precios especificado. Los valores válidos se encuentran en el rango que se extiende de 0 (más asequible) a 4 (más costoso), inclusive.
    • Cualquiera de los siguientes:
      • bounds, que debe ser un objeto google.maps.LatLngBounds que defina el área de búsqueda rectangular. La distancia diagonal máxima admitida para el área de límites es de aproximadamente 100,000 metros.
      • location y radius: Puedes personalizar los resultados para un círculo específico si pasas los parámetros location y radius. Esto le indicará al servicio Google Places que muestre preferentemente los resultados que se encuentran dentro de ese círculo. Es posible que también se muestren resultados externos al área definida. La ubicación toma un objeto google.maps.LatLng, y el radio toma un número entero que representa el radio del círculo en metros. El radio máximo permitido es de 50,000 metros.
    • type: Restringe los resultados a los lugares que coinciden con el tipo especificado. Solo se puede especificar un tipo (si se proporciona más de un tipo, se ignoran todos los siguientes a la primera entrada). Consulta la lista de tipos compatibles.

También debes pasar un método de devolución de llamada a textSearch() para controlar el objeto de resultados y una respuesta google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Respuestas de búsqueda

Códigos de estado

El objeto de respuesta PlacesServiceStatus contiene el estado de la solicitud y puede incluir información de depuración para ayudarte a identificar el motivo del error en la solicitud de lugar. Los posibles valores de estado son los siguientes:

  • INVALID_REQUEST: Esta solicitud no es válida.
  • OK: La respuesta contiene un resultado válido.
  • OVER_QUERY_LIMIT: La página web excedió su cuota de solicitudes.
  • REQUEST_DENIED: La página web no puede usar PlacesService.
  • UNKNOWN_ERROR: No se pudo procesar la solicitud de PlacesService debido a un error de servidor. La solicitud podría completarse si realizas un nuevo intento.
  • ZERO_RESULTS: No se encontraron resultados para esta solicitud.

Resultados de Place Search

Las funciones findPlace(), nearbySearch() y textSearch() muestran un array de objetos PlaceResult.

Cada objeto PlaceResult puede incluir las siguientes propiedades:

  • business_status indica el estado operativo del lugar, si es una empresa. Puede contener uno de los siguientes valores:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Si no hay datos, no se muestra business_status.
  • formatted_address es una cadena que contiene la dirección legible por humanos de este lugar. La propiedad formatted_address solo se muestra para las solicitudes de Text Search.

    A menudo, esta dirección equivale a la "dirección postal". Ten en cuenta que, en algunos países, como los que integran el Reino Unido, no se permite la distribución de direcciones postales verdaderas debido a restricciones de licencia.

    La dirección con formato está compuesta, de manera lógica, por uno o más componentes de dirección. Por ejemplo, la dirección "111 8th Avenue, New York, NY" consta de los siguientes componentes: "111" (número de la calle), "8th Avenue" (calle), "New York" (ciudad) y "NY" (estado de los EE.UU.).

    No analices la dirección con formato por vía programática. En cambio, utiliza los componentes individuales de la dirección, que la respuesta de la API incluye además del campo de dirección con formato.

  • geometry: Muestra información del lugar relacionada con aspectos geométricos. Esto incluye lo siguiente:
    • location: Proporciona la latitud y la longitud del lugar.
    • viewport: Define el viewport preferido en el mapa cuando se visualiza este lugar.
  • permanently_closed (obsoleto): Es un marcador booleano que indica si el lugar se cerró de forma permanente o temporal (valor true). No uses permanently_closed. En cambio, utiliza business_status para conocer el estado operativo de las empresas.
  • plus_code (consulta Código de ubicación abierto y Plus Codes): Es una referencia de ubicación codificada, derivada de las coordenadas de latitud y longitud, que representa un área: 1/8,000 de un grado por 1/8,000 de un grado (aproximadamente 14 m x 14 m en el Ecuador) o menos. Los Plus Codes se pueden usar como reemplazo de las direcciones en los lugares donde estas no existen (donde los edificios no están numerados o las calles no tienen nombre).

    Estos códigos tienen el formato de un código global y un código compuesto:

    • global_code: Es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9).
    • compound_code: Es un código local de 6 caracteres o más con una ubicación explícita (CWC8+R9, Mountain View, CA, EE.UU.). No analices este contenido de forma programática.
    Por lo general, se muestran tanto el código global como el compuesto. Sin embargo, si el resultado corresponde a una ubicación remota (por ejemplo, un océano o un desierto), solo se puede mostrar el código global.
  • html_attributions: Es un array de atribuciones que debes mostrar al exhibir los resultados de la búsqueda. Cada entrada del array contiene el texto HTML de una atribución simple. Nota: Esto representa una agregación de todas las atribuciones de la respuesta de búsqueda. Por lo tanto, todos los objetos PlaceResult de la respuesta contienen listas de atribución idénticas.
  • icon: Muestra la URL de un ícono PNG de color de 71 x 71 px.
  • icon_mask_base_uri: Muestra la URL base de un ícono sin color, menos las extensiones .svg o .png.
  • icon_background_color: Muestra el código de color hexadecimal predeterminado para la categoría del lugar.
  • name: Muestra el nombre del lugar.
  • opening_hours: Puede contener la siguiente información:
    • open_now: Es un valor booleano que indica si el lugar está abierto en el momento actual (obsoleto en la biblioteca de Places de la API de Maps JavaScript; usa utc_offset_minutes en su lugar).
  • place_id: Es un identificador textual que identifica un lugar de forma exclusiva. Para obtener información sobre el lugar, pasa este identificador en la solicitud de Place Details. Obtén más información sobre cómo hacer referencia a un lugar con un ID de lugar.
  • rating: Contiene la calificación del lugar, de 0.0 a 5.0, según las opiniones agregadas de los usuarios.
  • types: Es un array de tipos para este lugar (p. ej., ["political", "locality"] o ["restaurant", "lodging"]). Este array puede contener varios valores o puede estar vacío. Se pueden ingresar valores nuevos sin aviso previo. Consulta la lista de tipos admitidos.
  • vicinity: Es una dirección simplificada del lugar, que incluye el nombre de la calle, el número y la localidad, pero no la provincia o el estado, el código postal ni el país. Por ejemplo, la oficina de Google en Sídney, Australia, tiene un valor de vicinity de 5/48 Pirrama Road, Pyrmont.

Cómo acceder a resultados adicionales

De manera predeterminada, cada búsqueda de lugar muestra hasta 20 resultados por consulta. Sin embargo, cada búsqueda puede arrojar hasta 60 resultados divididos en tres páginas. Hay páginas adicionales disponibles a través del objeto PlaceSearchPagination. Para acceder a las páginas adicionales, debes capturar el objeto PlaceSearchPagination mediante una función de devolución de llamada. El objeto PlaceSearchPagination se define de la siguiente manera:

  • hasNextPage: Es una propiedad booleana que indica si hay más resultados disponibles. El valor es true cuando hay una página de resultados adicional.
  • nextPage(): Es una función que muestra el siguiente conjunto de resultados. Una vez que se ejecute la búsqueda, debes esperar dos segundos para que esté disponible la página siguiente.

Si deseas ver el siguiente conjunto de resultados, llama a nextPage. Se debe mostrar cada página de resultados antes de que aparezca la siguiente. Ten en cuenta que cada búsqueda cuenta como una solicitud única para tus límites de uso.

En el siguiente ejemplo, se muestra cómo modificar la función de devolución de llamada para capturar el objeto PlaceSearchPagination para que puedas emitir varias solicitudes de búsqueda.

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

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

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
Ver ejemplo

Prueba la muestra

Place Details

Además de proporcionar una lista de lugares en un área, el servicio Places también puede mostrar información detallada sobre un lugar específico. Una vez que un lugar se muestra en una respuesta de búsqueda de lugares, el ID de lugar correspondiente se puede utilizar para solicitar detalles adicionales sobre el lugar, como su dirección completa y el número de teléfono, así como la calificación y las opiniones de los usuarios.

Solicitudes de Place Details

Las solicitudes de Place Details se realizan con una llamada al método getDetails() del servicio.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

Este método requiere una solicitud, que contiene el placeId del lugar deseado, y campos que indican qué tipos de datos de Places se devolverán. Obtén más información sobre cómo hacer referencia a un lugar con un ID de lugar.

También requiere un método de devolución de llamada, que debe controlar el código de estado que se pasó en la respuesta de google.maps.places.PlacesServiceStatus, así como el objeto google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

Ver ejemplo

Campos (Place Details)

El parámetro fields requiere un array de cadenas (nombres de campo).

Usa el parámetro fields para especificar un array de los tipos de datos de lugar que deseas que se muestren. Por ejemplo: fields: ['address_components', 'opening_hours', 'geometry']. Usa un punto para especificar valores compuestos. Por ejemplo: opening_hours.weekday_text.

Los campos corresponden a los resultados de Place Details y se dividen en tres categorías de facturación: Basic, Contact y Atmosphere. Los campos de la tarifa Basic se facturan con la tarifa base y no generan cargos adicionales. Los campos de datos de contacto y atmosféricos se facturan con una tarifa más alta. Consulta la hoja de precios para obtener más información. Las atribuciones (html_attributions) se muestran con todas las llamadas, independientemente de si se solicitó el campo.

Basic

La categoría Basic incluye los siguientes campos:
address_components ,adr_address ,business_status ,formatted_address ,geometry ,icon ,icon_mask_base_uri ,icon_background_color ,name ,permanently_closed (obsoleto),photo ,place_id ,plus_code ,type ,url ,utc_offset (obsoleto en la Biblioteca de Places de la API de Maps JavaScript),utc_offset_minutes y vicinity.

Contact

La categoría Contact incluye los siguientes campos:
formatted_phone_number, international_phone_number, opening_hours y website.

Atmosphere

La categoría Atmosphere incluye los siguientes campos: price_level, rating, reviews y user_ratings_total.

Obtén más información sobre los campos de lugares. Si deseas consultar más detalles sobre cómo se facturan las solicitudes de datos de Places, consulta Uso y facturación.

Respuestas de Place Details

Códigos de estado

El objeto de respuesta PlacesServiceStatus contiene el estado de la solicitud y puede contener información de depuración para ayudarte a identificar el motivo de error en la solicitud de Place Details. Los posibles valores de estado son los siguientes:

  • INVALID_REQUEST: Esta solicitud no es válida.
  • OK: La respuesta contiene un resultado válido.
  • OVER_QUERY_LIMIT: La página web excedió su cuota de solicitudes.
  • NOT_FOUND La ubicación a la que se hace referencia no se encontró en la base de datos de Places.
  • REQUEST_DENIED: La página web no puede usar PlacesService.
  • UNKNOWN_ERROR: No se pudo procesar la solicitud de PlacesService debido a un error de servidor. La solicitud podría completarse si realizas un nuevo intento.
  • ZERO_RESULTS: No se encontraron resultados para esta solicitud.

Resultados de Place Details

Una llamada a getDetails() exitosa muestra un objeto PlaceResult con las siguientes propiedades:

  • address_components: Es un array que incluye los componentes independientes aplicables a esta dirección.

    Por lo general, cada componente de la dirección incluye los siguientes campos:

    • types[]: Es un array que indica el tipo de componente de la dirección. Consulta la lista de tipos admitidos.
    • long_name: Es la descripción textual completa o el nombre del componente de la dirección que muestra el geocodificador.
    • short_name: Es un nombre textual abreviado para el componente de la dirección si está disponible. Por ejemplo, un componente de dirección para el estado de Alaska puede tener un long_name de "Alaska" y un short_name de "AK" con la abreviatura postal de 2 letras.

    Ten en cuenta lo siguiente acerca del array address_components[]:

    • El array de componentes de dirección puede incluir más componentes que formatted_address.
    • El array no necesariamente incluye todas las entidades políticas que contienen una dirección, además de las incluidas en formatted_address. Para obtener datos sobre todas las entidades políticas que contienen una dirección específica, debes usar la geocodificación inversa, y pasar la latitud y la longitud de la dirección como parámetro a la solicitud.
    • No se garantiza que el formato de la respuesta permanezca igual entre las distintas solicitudes. En particular, la cantidad de address_components varía según la dirección solicitada y puede cambiar con el tiempo para la misma dirección. Un componente puede cambiar de posición en el array. El tipo de componente puede cambiar. Es posible que falte un componente en particular en una respuesta posterior.
  • business_status indica el estado operativo del lugar, si es una empresa. Puede contener uno de los siguientes valores:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Si no hay datos, no se muestra business_status.
  • formatted_address: Es la dirección de este lugar en lenguaje natural.

    A menudo, esta dirección equivale a la "dirección postal". Ten en cuenta que, en algunos países, como los que integran el Reino Unido, no se permite la distribución de direcciones postales verdaderas debido a restricciones de licencia.

    La dirección con formato está compuesta, de manera lógica, por uno o más componentes de dirección. Por ejemplo, la dirección "111 8th Avenue, New York, NY" consta de los siguientes componentes: "111" (número de la calle), "8th Avenue" (calle), "New York" (ciudad) y "NY" (estado de los EE.UU.).

    No analices la dirección con formato por vía programática. En cambio, utiliza los componentes individuales de la dirección, que la respuesta de la API incluye además del campo de dirección con formato.

  • formatted_phone_number: Es el número de teléfono del lugar, con el formato indicado en la convención regional de números.
  • geometry: Muestra información del lugar relacionada con aspectos geométricos. Esto incluye lo siguiente:
    • location: Proporciona la latitud y la longitud del lugar.
    • viewport: Define el viewport preferido en el mapa cuando se visualiza este lugar.
  • permanently_closed (obsoleto): Es un marcador booleano que indica si el lugar se cerró de forma permanente o temporal (valor true). No uses permanently_closed. En cambio, utiliza business_status para conocer el estado operativo de las empresas.
  • plus_code (consulta Código de ubicación abierto y Plus Codes): Es una referencia de ubicación codificada, derivada de las coordenadas de latitud y longitud, que representa un área: 1/8,000 de un grado por 1/8,000 de un grado (aproximadamente 14 m x 14 m en el Ecuador) o menos. Los Plus Codes se pueden usar como reemplazo de las direcciones en los lugares donde estas no existen (donde los edificios no están numerados o las calles no tienen nombre).

    Estos códigos tienen el formato de un código global y un código compuesto:

    • global_code: Es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9).
    • compound_code: Es un código local de 6 caracteres o más con una ubicación explícita (CWC8+R9, Mountain View, CA, EE.UU.). No analices este contenido de forma programática.
    Por lo general, se muestran tanto el código global como el compuesto. Sin embargo, si el resultado corresponde a una ubicación remota (por ejemplo, un océano o un desierto), solo se puede mostrar el código global.
  • html_attributions: Es el texto de atribución que se debe mostrar para este resultado de lugar.
  • icon: Es la URL de un recurso de imagen que se puede usar para representar el tipo de sitio.
  • international_phone_number: Contiene el número de teléfono del lugar en formato internacional. Este formato incluye el código de país y está precedido por un signo más (+). Por ejemplo, el international_phone_number de la oficina de Google en Sídney, Australia, es +61 2 9374 4000.
  • name: Muestra el nombre del lugar.
  • utc_offset: Se encuentra obsoleto en la Biblioteca de Places de la API de Maps JavaScript. Usa utc_offset_minutes en su lugar.
  • utc_offset_minutes contiene la cantidad de minutos de diferencia de la zona horaria actual del lugar con respecto a la zona UTC. Por ejemplo, para lugares ubicados en Sídney, Australia, durante el horario de verano, esta cifra sería 660 (+11 horas respecto de UTC) y, para lugares ubicados en California fuera del horario de verano, sería -480 (-8 horas respecto de UTC).
  • opening_hours: Contiene la siguiente información:
    • open_now (obsoleto en la biblioteca de Places de la API de Maps JavaScript; usa opening_hours.isOpen() en su lugar. Consulta este video para obtener información sobre cómo usar isOpen con Place Details): Es un valor booleano que indica si el lugar está abierto en ese momento.
    • periods[]: Es un array de períodos de atención que cubren siete días, a partir del domingo, en orden cronológico. Cada período contiene lo siguiente:
      • open: Contiene un par de objetos de día y hora que indican cuándo abre el lugar:
        • day: Es un número del 0 al 6 que corresponde a los días de la semana a partir del domingo. Por ejemplo, "2" significa "martes".
        • time: Puede contener una hora del día en el formato hhmm de 24 horas (los valores se muestran en el rango de 0000 a 2359). El objeto time se informa en la zona horaria del lugar.
      • close: Puede contener un par de objetos de día y hora que indican cuándo cierra el lugar. Nota: Si un lugar está siempre abierto, la sección close no aparecerá en la respuesta. Algunas aplicaciones pueden requerir que la indicación "siempre abierto" se represente como un período open con el valor 0 en day y 0000 en time, y que no se indique un elemento close.
    • weekday_text: Es un array de siete cadenas que representan los horarios de atención con formato para cada día de la semana. Si se especificó un parámetro language en la solicitud de Place Details, el servicio Places dará formato al horario de atención y lo localizará de forma adecuada para ese idioma. El orden de los elementos en este array depende del parámetro language. En algunos idiomas, la semana comienza el lunes y, en otros, el domingo.
  • permanently_closed (obsoleto): Es un marcador booleano que indica si el lugar se cerró de forma permanente o temporal (valor true). No uses permanently_closed. En cambio, utiliza business_status para conocer el estado operativo de las empresas.
  • photos[]: Es un array de objetos PlacePhoto. Se puede utilizar un objeto PlacePhoto para obtener una foto con el método getUrl(), o bien puedes inspeccionar el objeto en busca de los siguientes valores:
    • height: Es la altura máxima de la imagen en píxeles.
    • width: Es el ancho máximo de la imagen en píxeles.
    • html_attributions: Es el texto de atribución que debe mostrarse con la foto del sitio.
  • place_id: Es un identificador textual que identifica un lugar de forma exclusiva y que se puede usar para obtener información sobre el lugar a través de una solicitud de Place Details. Obtén más información sobre cómo hacer referencia a un lugar con un ID de lugar.
  • rating: Es la calificación del lugar, de 0.0 a 5.0, según las opiniones agregadas de los usuarios.
  • reviews: Es un array de hasta cinco opiniones. Cada opinión consta de varios componentes:
    • aspects[]: Contiene un array de objetos PlaceAspectRating, cada uno de los cuales proporciona una calificación de un atributo del establecimiento. El primer objeto del array se considera el aspecto principal. Cada PlaceAspectRating se define de la siguiente manera:
      • type: Es el nombre del aspecto que se está calificando. Se admiten los siguientes tipos: appeal, atmosphere, decor, facilities, food, overall, quality y service.
      • rating: Es la calificación del usuario para el aspecto en particular, en una escala de 0 a 3.
    • author_name: Es el nombre del usuario que envió la opinión. Las opiniones anónimas se atribuyen a "Un usuario de Google". Si se estableció un parámetro de idioma, la frase "Un usuario de Google" devolverá una cadena localizada.
    • author_url: Es la URL del perfil de Google+ de los usuarios, si está disponible.
    • language: Es un código de idioma IETF correspondiente a la opinión del usuario. Este campo contiene solo la etiqueta del idioma principal y no la etiqueta secundaria que indica el país o la región. Por ejemplo, todas las opiniones en inglés están etiquetadas como "en", y no como "en-AU" o "en-UK", etcétera.
    • rating: Es la calificación general del usuario para este lugar. Se representa con un número entero del 1 al 5.
    • text: Es la opinión del usuario. Al revisar una ubicación con Google Places, las opiniones de texto se consideran opcionales. Por lo tanto, este campo puede estar vacío.
  • types: Es un array de tipos para este lugar (p. ej., ["political", "locality"] o ["restaurant", "lodging"]). Este array puede contener varios valores o puede estar vacío. Se pueden ingresar valores nuevos sin aviso previo. Consulta la lista de tipos admitidos.
  • url: Es la URL de la página oficial de Google del lugar. Es la página de Google que contiene la mejor información disponible acerca del lugar. Las aplicaciones deben establecer un vínculo con esta página o incorporarla en cualquiera de las pantallas que muestren al usuario resultados detallados sobre el lugar.
  • vicinity: Es una dirección simplificada del lugar, que incluye el nombre de la calle, el número y la localidad, pero no la provincia o el estado, el código postal ni el país. Por ejemplo, la oficina de Google en Sídney, Australia, tiene un valor de vicinity de 5/48 Pirrama Road, Pyrmont. La propiedad vicinity solo se muestra para las solicitudes de Nearby Search.
  • website: Indica cuál es el sitio web autorizado para este lugar, por ejemplo, la página principal de una empresa.

Nota: Es posible que las calificaciones multidimensionales no estén disponibles para todas las ubicaciones. Si hay muy pocas opiniones, la respuesta de detalles incluirá una calificación heredada en una escala de 0.0 a 5.0 (si estuviera disponible) o no incluirá ninguna calificación.

Cómo hacer referencia a un lugar con un ID de lugar

Un ID de lugar es una referencia única a un lugar en un mapa de Google Maps. Los IDs de lugar están disponibles para la mayoría de las ubicaciones, incluidos puntos de referencia, empresas, intersecciones y parques.

Para usar un ID de lugar en tu app, primero debes buscar el ID, que está disponible en el elemento PlaceResult de una solicitud de Place Search o Place Details. Luego, puedes usar este ID de lugar para buscar Place Details.

Los IDs de lugar están exentos de las restricciones de almacenamiento en caché establecidas en el Artículo 3.2.3(b) de las Condiciones del Servicio de Google Maps Platform. Por lo tanto, puedes almacenar valores de ID de lugar para usarlos en otro momento. Si deseas conocer las prácticas recomendadas para almacenar los IDs de lugar, consulta la descripción general de los IDs de lugar.

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

Place Photos

La función Place Photos te permite agregar contenido fotográfico de alta calidad a tu sitio. El servicio Photos te brinda acceso a las millones de fotos almacenadas en la base de datos de Places y Lugares. Si obtienes información sobre lugares mediante una solicitud de Place Details, se devolverán referencias de fotos para el contenido fotográfico correspondiente. Las solicitudes de Nearby Search y Text Search también muestran una única referencia fotográfica por lugar, cuando corresponde. El servicio Photos te brinda acceso a las fotos de referencia y te permite cambiar el tamaño de la imagen al más adecuado para tu aplicación.

Se mostrará un array de objetos PlacePhoto como parte del objeto PlaceResult para cualquier solicitud de getDetails(), textSearch() o nearbySearch() realizada en un PlacesService.

Nota: La cantidad de fotos que se muestran varía según la solicitud.

  • Las solicitudes de Nearby Search o Text Search mostrarán, como máximo, un objeto PlacePhoto.
  • Las solicitudes de Place Details pueden mostrar hasta diez objetos PlacePhoto.

Para solicitar la URL de la imagen asociada, debes llamar al método PlacePhoto.getUrl() y pasar un objeto PhotoOptions válido. El objeto PhotoOptions te permite especificar la altura y el ancho máximos deseados para la imagen. Si especificas un valor para maxHeight y maxWidth, el servicio de fotos cambiará el tamaño de la imagen al más pequeño y conservará la relación de aspecto original.

En el siguiente fragmento de código, se acepta un objeto de lugar y se agrega un marcador al mapa si existe una foto. La imagen predeterminada del marcador se reemplaza por una versión pequeña de la foto.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

Las fotos que muestra el servicio Photos provienen de una variedad de fuentes, incluidas las fotos proporcionadas por los propietarios de las empresas y los aportes de los usuarios. En la mayoría de los casos, estas fotos se pueden utilizar sin atribución; de lo contrario, incluirán la atribución requerida como parte de la imagen. Sin embargo, si el elemento photo que se muestra incluye un valor en el campo html_attributions, deberás incluir la atribución adicional en tu aplicación en cualquier lugar donde muestres la imagen.