biblioteca de Places

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.
Seleccionar plataforma: Android iOS JavaScript Servicio web

Descripción general

Las funciones de la Biblioteca de Places para la API de Maps JavaScript permiten que tu aplicación busque lugares (definidos en esta API como establecimientos, ubicaciones geográficas o puntos de interés destacados) dentro de un área definida, como los límites de un mapa o alrededor de 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, el autocompletado completa el resto. Para obtener más información, consulta la documentación sobre el autocompletado.

Cómo comenzar

Si no estás familiarizado con la API de Maps JavaScript o con JavaScript, te recomendamos revisar JavaScript y Obtener una clave de API antes de comenzar.

Habilite las API

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

Para ver tu lista de API habilitadas:

  1. Ve a Google Cloud Console.
  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 API del Panel, busca API de Places.
  4. Si ves la API de Places en la lista, significa que ya está habilitada. Si la API no está en la lista, habilítala:
    1. En la parte superior de la página, selecciona HABILITAR API Y SERVICIOS para mostrar la pestaña Biblioteca. Como alternativa, en el menú lateral izquierdo, selecciona Biblioteca.
    2. Busca API de Places y selecciónala en la lista de resultados.
    3. Selecciona HABILITAR. Cuando finalice el proceso, la API de Places aparecerá en la lista de API del Panel.

Cargar la biblioteca

El servicio de 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&libraries=places&callback=initMap">
</script>

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

Agregar la API de Places a la lista de restricciones de la API de la clave de API

Aplicar restricciones de API a tus claves limita el uso de la clave de API a uno o más SDK o API. Se procesarán las solicitudes a una API o SDK asociados con la clave de API. Las solicitudes a una API o SDK que no estén asociadas con la clave de API fallarán. Para restringir una clave de API a fin de usarla con la biblioteca de Places para la API de Maps JavaScript, haz lo siguiente:
  1. Ve a Google Cloud Console.
  2. Haz clic en el menú desplegable del proyecto y selecciona el proyecto que contiene 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 la API
      • Selecciona Restringir clave.
      • Haga clic en Seleccionar API y seleccione API de Maps JavaScript y API de Places.
        (Si alguna de las API no aparece en la lista, debes habilitarla).
  6. Haz clic en GUARDAR.

Límites y políticas de uso

Cuotas

La Biblioteca de Places para la API de JavaScript comparte una cuota de uso con la API de Places, como se describe en la documentación de los límites de uso de la API de Places. El límite de frecuencia de consultas por segundo se aplica por sesión de usuario, independientemente de la cantidad de usuarios que compartan el mismo proyecto.*

Nota: Cuando cargas la API por primera vez, se te asigna una cuota inicial de solicitudes. Una vez que usas esta cuota, la API aplica límites de frecuencia sobre las solicitudes adicionales por segundo. Si se realizan demasiadas solicitudes en un período determinado, la API muestra un código de respuesta OVER_QUERY_LIMIT. El límite de frecuencia por sesión evita el uso de servicios del cliente para solicitudes por lotes. Para solicitudes por lotes, usa nuestras API de servicio web.

Políticas

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

Búsquedas de sitios

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

La información que se muestra puede incluir establecimientos, como restaurantes, tiendas y oficinas, así como resultados de geocódigos que indican direcciones, áreas políticas, como pueblos y ciudades, y otros lugares de interés.

Solicitudes de Find Place

Una solicitud a Find Place te permite buscar un lugar por texto o número de teléfono. Existen dos tipos de solicitudes de Find Place:

Buscar lugar a partir de la consulta

Find Place de la consulta toma una entrada de texto y muestra un lugar. La entrada puede ser cualquier tipo de dato de lugar, por ejemplo, el nombre o la dirección de una empresa. Para realizar una solicitud a Find Place a partir de una consulta, llama al método findPlaceFromQuery() de PlaceService, que toma los siguientes parámetros:

  • query (obligatorio) Es la string de texto en la que se busca, por ejemplo: &restaurant; o "123 Main Street". Debe ser el nombre de un lugar, una dirección o una categoría de establecimientos. Cualquier otro tipo de entrada puede generar errores y no se garantiza que muestren resultados válidos. La API de Places mostrará coincidencias de candidatos en función de esta string 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 mostrarán.
  • locationBias (opcional) Define las coordenadas en las que se va a buscar. Puede ser una de las siguientes opciones:
    • Un conjunto de coordenadas de latitud y longitud especificadas como LatLngLiteral o Objeto LatLng
    • Límites rectangulares (dos pares de latitud y longitud o un objeto LatLngBounds)
    • Radio (en metros) centrado en una latitud y longitud

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

En el siguiente ejemplo, se muestra una llamada a findPlaceFromQuery(), en la que se busca el “Museo de Arte Contemporáneo de Australia” y que 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

Buscar lugar a partir del número de teléfono

La función Encontrar lugar del número de teléfono toma un número de teléfono y devuelve un lugar. Para realizar una solicitud a Find Place a partir del número de teléfono, llama al método findPlaceFromPhoneNumber() de PlaceService, que toma los siguientes parámetros:

  • phoneNumber (obligatorio): 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 mostrarán.
  • locationBias (opcional) Coordina las áreas que se deben buscar. Puede ser una de las siguientes opciones:
    • Un conjunto de coordenadas de latitud y longitud especificadas como LatLngLiteral o Objeto LatLng
    • Límites rectangulares (cuatro puntos de latitud y longitud o un objeto LatLngBounds)
    • Radio (en metros) centrado en una latitud y longitud

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

Campos (métodos de Find Place)

Usa el parámetro fields para especificar un arreglo de tipos de datos de sitios que se mostrarán. Por ejemplo: fields: ['formatted_address', 'opening_hours', 'geometry'] Usa un punto cuando especifiques valores compuestos. Por ejemplo: opening_hours.weekday_text.

Los campos corresponden a los resultados de la búsqueda de lugares y se dividen en tres categorías de facturación: Basic, Contact y Atmosphere. Los campos básicos se facturan a la tarifa base y no generan cargos adicionales. Los campos 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) siempre se muestran con cada llamada, sin importar si se solicitó el campo.

Básica

La categoría básica 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, types

Contacto

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

Ambiente

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

Cada uno de los métodos findPlaceFromQuery() y findPlaceFromPhoneNumber() toma el mismo conjunto de campos y puede mostrar los mismos campos en sus respectivas respuestas.

Cómo establecer el sesgo de ubicación (métodos de Find Place)

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

Sesgo de resultados para un área específica:

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

Define un área rectangular para buscar:

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

También puedes usar un LatLngBounds.

Defina un radio para buscar (en metros), centrado en un área en particular:

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

Solicitudes de búsquedas de sitios cercanos

Una búsqueda de sitios cercanos te permite buscar lugares dentro de un área específica por palabra clave o tipo. Una búsqueda de sitios cercanos siempre debe incluir una ubicación, que se puede especificar de una de estas dos formas:

  • 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 con una llamada al método nearbySearch() de PlacesService, que mostrará un arreglo 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:

  • Elija una de las siguientes opciones:
    • bounds, que debe ser un objeto google.maps.LatLngBounds que defina el área de búsqueda rectangular; o
    • un location y un radius; el primero toma un objeto google.maps.LatLng y el segundo toma un número entero simple, 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 un location, pero no puedes especificar un radius o bounds.
  • keyword (opcional): un término para comparar con todos los campos disponibles, incluidos, entre otros, nombre, tipo y dirección, así como opiniones de los clientes y otro contenido de terceros.
  • minPriceLevel y maxPriceLevel (opcional): Restringe los resultados a solo aquellos lugares dentro del rango especificado. Los valores válidos varían entre 0 (más asequibles) y 4 (más costosos), inclusive.
  • name desactivado. 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): 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 sitios que no especifican los horarios de apertura 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 efecto.
  • rankBy (opcional): Especifica el orden en el que se muestran los resultados. Los valores posibles son los siguientes:
    • google.maps.places.RankBy.PROMINENCE (predeterminado) Con esta opción, se ordenan los resultados según su importancia. La clasificación dará prioridad a los lugares destacados dentro del radio establecido en lugar de los lugares cercanos que coincidan, pero que sean menos destacados. La importancia se puede ver 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 por su distancia del location especificado (obligatorio). Ten en cuenta que no puedes especificar un bounds o radius personalizados si especificas RankBy.DISTANCE. Cuando especificas RankBy.DISTANCE, se requiere uno o más de keyword, name o type.
  • type: Restringe los resultados a 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 tipos que siguen a la primera entrada). Consulta la lista de tipos compatibles.

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 búsquedas de texto

El servicio de búsqueda de texto de Google Places es un servicio web que devuelve información sobre un conjunto de sitios basados en una cadena; por ejemplo, &pizza en Nueva York o tiendas de zapatos cerca de Ottawa. El servicio responde con una lista de sitios que coinciden con la string de texto y cualquier sesgo de ubicación que se haya establecido. En la respuesta de búsqueda se incluye una lista de sitios. Puedes enviar 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): String de texto en la que se realiza 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 y no se garantiza que muestren resultados válidos. El servicio de Places mostrará posibles coincidencias en función de esta string y ordenará los resultados según la relevancia percibida. Este parámetro se vuelve opcional si el parámetro type también se usa en la solicitud de búsqueda.
  • De manera opcional, haz lo siguiente:
    • openNow: 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 sitios que no especifican los horarios de apertura 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 efecto.
    • minPriceLevel y maxPriceLevel: restringe los resultados solo a esos lugares dentro del nivel de precios especificado. Los valores válidos se encuentran en el rango de 0 (más asequible) a 4 (más costoso), inclusive.
    • Elija una de las siguientes opciones:
      • bounds: Es un objeto google.maps.LatLngBounds que define el rectángulo en el que se realizará la búsqueda.
      • location y radius: puedes restringir los resultados a un círculo especificado si pasas un parámetro location y radius. Esto le indicará al servicio de Places que muestre preferentemente resultados dentro de ese círculo. Es posible que aú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 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 tipos que siguen 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 contener información de depuración para ayudarte a localizar por qué falló 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 superó la cuota de solicitudes.
  • REQUEST_DENIED: La página web no puede usar PlacesService.
  • UNKNOWN_ERROR: No se pudo procesar la solicitud a PlacesService debido a un error del servidor. La solicitud puede tener éxito si realizas un nuevo intento.
  • ZERO_RESULTS: No se encontró ningún resultado para esta solicitud.

Resultados de búsqueda de sitios

Las funciones findPlace(), nearbySearch() y textSearch() muestran un arreglo 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 existen datos, no se muestra business_status.
  • formatted_address es una string que contiene la dirección legible de este lugar. La propiedad formatted_address solo se muestra para una búsqueda de texto.

    A menudo, esta dirección es equivalente a la dirección postal. Ten en cuenta que algunos países, como el Reino Unido, no permiten la distribución de direcciones postales verdaderas debido a restricciones de licencias.

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

    No analices la dirección con formato de manera programática. En su lugar, debes usar los componentes de dirección individuales, que la respuesta de la API incluye, además del campo de dirección con formato.

  • geometry: la información relacionada con la geometría del lugar. Esto incluye lo siguiente:
    • location proporciona la latitud y longitud del lugar.
    • viewport define el viewport preferido en el mapa cuando se visualiza este lugar.
  • permanently_closed (obsoleto) es una marca booleana que indica si el lugar se cerró de forma permanente o temporal (valor true). No uses permanently_closed. En su lugar, usa business_status para obtener el estado operativo de las empresas.
  • plus_code (consulta el Código de ubicación abierta y los códigos plus) es una referencia de ubicación codificada, derivada de coordenadas de latitud y longitud, que representa un área: 1/8000 de un grado por 1/8000 de grado (aproximadamente 14 m x 14 m en el Ecuador) o menos. Los Plus Codes se pueden usar como reemplazo de las direcciones en lugares donde no existen (donde los edificios no están numerados o las calles no tienen nombre).

    El código plus tiene 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 manera programática.
    Por lo general, se muestran el código global y el compuesto. Sin embargo, si el resultado está en una ubicación remota (por ejemplo, un océano o un desierto), solo se puede mostrar el código global.
  • html_attributions: Es un arreglo de atribuciones que debes mostrar cuando muestras los resultados de la búsqueda. Cada entrada del arreglo contiene el texto HTML para una sola atribución. Nota: Esta es una agregación de todas las atribuciones de toda 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 71 px x 71 px de color.
  • icon_mask_base_uri muestra la URL base de un ícono que no es de color, menos la extensión .svg o .png.
  • icon_background_color muestra el código de color hexadecimal predeterminado para la categoría del lugar.
  • name: 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 ese momento (obsoleto en la biblioteca de Places para la API de Maps JavaScript; usa utc_offset_minutes en su lugar).
  • place_id es un identificador textual que identifica de forma exclusiva un lugar. Para recuperar información sobre el lugar, pasa este identificador en la solicitud de detalles del lugar. Obtén más información sobre cómo hacer referencia a un sitio 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: Corresponde a un arreglo de tipos de este lugar (p.ej., ["political", "locality"] o ["restaurant", "lodging"]). Este arreglo puede contener varios valores o puede estar vacío. Se pueden ingresar valores nuevos sin previo aviso. Consulta la lista de tipos admitidos.
  • vicinity: Es una dirección simplificada para el lugar, que incluye el nombre de la calle, el número de la calle 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.

Acceso a resultados adicionales

De manera predeterminada, cada búsqueda de sitios devuelve hasta 20 resultados por consulta. Sin embargo, cada búsqueda puede mostrar hasta 60 resultados, divididos en tres páginas. Hay páginas adicionales disponibles a través del objeto PlaceSearchPagination. Para acceder a páginas adicionales, debes capturar el objeto PlaceSearchPagination a través de 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. true cuando hay una página de resultados adicional
  • nextPage() es una función que mostrará el siguiente conjunto de resultados. Después de ejecutar una búsqueda, debes esperar dos segundos para que la siguiente página de resultados esté disponible.

Para ver el siguiente conjunto de resultados, llama a nextPage. Se debe mostrar cada página de resultados antes de mostrar la siguiente. Ten en cuenta que cada búsqueda cuenta como una única solicitud respecto de 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, de modo 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;

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;
Ver ejemplo

Probar la muestra

Place Details

Además de proporcionar una lista de los lugares dentro de un área, el servicio de Places también puede devolver información detallada sobre un lugar específico. Una vez que se muestra un sitio en una respuesta de búsqueda de sitios, se puede usar su ID de lugar para solicitar detalles adicionales sobre ese sitio, como su dirección completa, su número de teléfono, las calificaciones y reseñas de los usuarios, etc.

Solicitudes de detalles del sitio

Los detalles de Place Details se solicitan mediante una llamada al método getDetails() del servicio.

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

Este método toma una solicitud que contiene el placeId deseado y los campos que indican los tipos de datos de Places que se deben mostrar. Obtén más información sobre cómo hacer referencia a un sitio con un ID de lugar.

También requiere un método de devolución de llamada, que debe controlar el código de estado pasado 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 (detalles del lugar)

El parámetro fields toma un arreglo de strings (nombres de campo).

Usa el parámetro fields para especificar un arreglo de tipos de datos de sitios que se mostrarán. Por ejemplo: fields: ['address_component', 'opening_hours', 'geometry'] Usa un punto cuando especifiques 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 básicos se facturan con la tarifa base y no generan cargos adicionales. Los campos Contacto y Atmósfera se facturan con una tarifa más alta. Consulta la hoja de precios para obtener más información. Las atribuciones (html_attributions) siempre se muestran con cada llamada, sin importar si se solicitó.

Básica

La categoría básica incluye los siguientes campos:
address_component, 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{/22 , en la Biblioteca de Mapsadr_address

Contacto

La categoría Contacto incluye los siguientes campos:
formatted_phone_number, international_phone_number, opening_hours, website

Ambiente

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

Obtén más información sobre los campos de lugar. Para obtener más información sobre cómo se facturan las solicitudes de datos de lugar, consulta Uso y facturación.

Respuestas de detalles del sitio

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 localizar por qué falló la solicitud a 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 superó la 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 a PlacesService debido a un error del servidor. La solicitud puede tener éxito si realizas un nuevo intento.
  • ZERO_RESULTS: No se encontró ningún resultado para esta solicitud.

Resultados de detalles del sitio

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

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

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

    • types[] es un arreglo que indica el tipo de componente de la dirección. Consulta la lista de tipos admitidos.
    • long_name es la descripción de texto completa o el nombre del componente de la dirección que muestra el codificador geográfico.
    • short_name es un nombre textual abreviado para el componente de 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 dos letras.

    Ten en cuenta los siguientes datos sobre el arreglo address_components[]:

    • El arreglo de componentes de dirección puede contener más componentes que formatted_address.
    • El arreglo no necesariamente incluye todas las entidades políticas que contienen una dirección, además de las incluidas en el formatted_address. Para recuperar todas las entidades políticas que contienen una dirección específica, debes usar la codificación geográfica inversa y pasar la latitud y longitud de la dirección como parámetro a la solicitud.
    • No se garantiza que el formato de la respuesta siga siendo el mismo entre 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 la posición en el arreglo. 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 existen datos, no se muestra business_status.
  • formatted_address: la dirección legible de este lugar.

    A menudo, esta dirección es equivalente a la dirección postal. Ten en cuenta que algunos países, como el Reino Unido, no permiten la distribución de direcciones postales verdaderas debido a restricciones de licencias.

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

    No analices la dirección con formato de manera programática. En su lugar, debes usar los componentes de dirección individuales, que la respuesta de la API incluye, además del campo de dirección con formato.

  • formatted_phone_number: el número de teléfono del lugar, con el formato correspondiente a la convención regional del número.
  • geometry: la información relacionada con la geometría del lugar. Esto incluye lo siguiente:
    • location proporciona la latitud y longitud del lugar.
    • viewport define el viewport preferido en el mapa cuando se visualiza este lugar.
  • permanently_closed (obsoleto) es una marca booleana que indica si el lugar se cerró de forma permanente o temporal (valor true). No uses permanently_closed. En su lugar, usa business_status para obtener el estado operativo de las empresas.
  • plus_code (consulta el Código de ubicación abierta y los códigos plus) es una referencia de ubicación codificada, derivada de coordenadas de latitud y longitud, que representa un área: 1/8000 de un grado por 1/8000 de grado (aproximadamente 14 m x 14 m en el Ecuador) o menos. Los Plus Codes se pueden usar como reemplazo de las direcciones en lugares donde no existen (donde los edificios no están numerados o las calles no tienen nombre).

    El código plus tiene 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 manera programática.
    Por lo general, se muestran el código global y el compuesto. Sin embargo, si el resultado está en una ubicación remota (por ejemplo, un océano o un desierto), solo se puede mostrar el código global.
  • html_attributions: texto de atribución que se mostrará para el resultado de este lugar.
  • icon: URL de un recurso de imagen que se puede usar para representar el tipo de este lugar.
  • international_phone_number contiene el número de teléfono del lugar en formato internacional. El formato internacional incluye el código de país y está precedido por el signo más (+). Por ejemplo, el international_phone_number de la oficina de Google en Sídney, Australia, es +61 2 9374 4000.
  • name: el nombre del lugar.
  • utc_offset Obsoleto en la Biblioteca de Places para la API de Maps JavaScript; usa utc_offset_minutes en su lugar.
  • utc_offset_minutes contiene la cantidad de minutos de desplazamiento de la zona horaria actual de este lugar respecto de UTC. Por ejemplo, para los lugares de Sídney, Australia, durante el horario de verano, sería de 660 (+11 horas de UTC) y para los lugares de California fuera del horario de verano de -480 (-8 horas para UTC).
  • opening_hours contiene la siguiente información:
    • open_now (obsoleto en la biblioteca de Places para la API de Maps JavaScript; en su lugar, usa opening_hours.isOpen()). 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 arreglo de períodos iniciales 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 describen cuándo se abre el lugar:
        • day 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 formato de 24 horas (los valores se encuentran en el rango de 0000 a 2359). El time se informará en la zona horaria del lugar.
      • close puede contener un par de objetos de día y hora que describen cuándo cierra el lugar. Nota: Si un lugar está siempre abierto, la sección close no aparecerá en la respuesta. Las aplicaciones pueden depender de que el estado siempre abierto se represente como un período open que contiene day con el valor 0 y time con el valor 0000, y ningún close.
    • weekday_text es un arreglo de siete strings que representan los horarios de apertura con formato para cada día de la semana. Si se especificó un parámetro language en la solicitud a Place Details, el servicio de Places dará formato a las horas de apertura y las localizará según corresponda para ese idioma. El orden de los elementos en este arreglo depende del parámetro language. Algunos idiomas comienzan la semana el lunes y otros el domingo.
  • permanently_closed (obsoleto) es una marca booleana que indica si el lugar se cerró de forma permanente o temporal (valor true). No uses permanently_closed. En su lugar, usa business_status para obtener el estado operativo de las empresas.
  • photos[]: Es un arreglo de objetos PlacePhoto. Se puede usar un PlacePhoto para obtener una foto con el método getUrl() o 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: texto de atribución que se mostrará con esta foto del lugar.
  • place_id: un identificador textual que identifica de forma exclusiva un lugar y que se puede usar para recuperar información sobre el lugar a través de una solicitud de detalles del sitio. Obtén más información sobre cómo hacer referencia a un sitio con un ID de lugar.
  • rating: la calificación del lugar, de 0.0 a 5.0, según las opiniones agregadas de los usuarios.
  • reviews un arreglo de hasta cinco opiniones. Cada opinión consta de varios componentes:
    • aspects[] contiene un arreglo de objetos PlaceAspectRating, cada uno de los cuales proporciona una calificación de un solo atributo del establecimiento. El primer objeto del arreglo se considera como 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 este aspecto específico, 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" mostrará una string localizada.
    • author_url la URL del perfil de Google+ de los usuarios, si está disponible.
    • language es un código de idioma IETF que indica el idioma utilizado en la revisión del usuario. Este campo contiene solo la etiqueta del idioma principal, no la etiqueta secundaria que indica el país o la región. Por ejemplo, todas las reseñas en inglés están etiquetadas como "'en" y no "'en-AU"'en-UK&#39, y así sucesivamente.
    • rating es la calificación general del usuario para este lugar. Es un número entero de 1 a 5.
    • text es la opinión del usuario. Al revisar una ubicación con Google Places, las revisiones de texto se consideran opcionales; por lo tanto, este campo puede estar vacío.
  • types: Corresponde a un arreglo de tipos de este lugar (p.ej., ["political", "locality"] o ["restaurant", "lodging"]). Este arreglo puede contener varios valores o puede estar vacío. Se pueden ingresar valores nuevos sin previo aviso. Consulta la lista de tipos admitidos.
  • url: Es la URL de la página oficial de Google para este lugar. Esta es la página de Google que contiene la mejor información disponible sobre el lugar. Las aplicaciones deben vincularse con esta página o incorporarla en cualquier pantalla que muestre resultados detallados sobre el lugar al usuario.
  • vicinity: Es una dirección simplificada para el lugar, que incluye el nombre de la calle, el número de la calle 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 una búsqueda de sitios cercanos.
  • website muestra el sitio web autorizado de este lugar, como 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 está disponible) o no incluirá calificación.

Cómo hacer referencia a un sitio con un id. de sitio

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

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

Los ID de lugar están exentos de las restricciones de almacenamiento en caché establecidas en la Sección 3.2.3(a) de las Condiciones del Servicio de Google Maps Platform. Por lo tanto, puedes almacenar valores de id. de sitio para uso posterior. Si deseas conocer las prácticas recomendadas para almacenar los ID de lugar, consulta la descripción general de ID 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);

Fotos del lugar

La función Foto de lugar te permite agregar contenido fotográfico de alta calidad a tu sitio. El servicio de fotos te brinda acceso a las millones de fotos almacenadas en la base de datos de Places y Google+ Local. Cuando obtienes información sobre sitios mediante una solicitud a Place Details, se mostrarán referencias de fotos para el contenido fotográfico relevante. Las solicitudes de búsqueda de sitios cercanos y de búsqueda de texto también muestran una sola referencia de foto por lugar, cuando es relevante. Con el servicio de fotos, puedes acceder a las fotos de referencia y cambiar el tamaño de la imagen al tamaño óptimo para tu aplicación.

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

Nota: La cantidad de fotos mostradas varía según la solicitud.

  • Una búsqueda de sitios cercanos o de texto mostrará, como máximo, un objeto PlacePhoto.
  • Una solicitud de detalles mostrará hasta diez objetos PlacePhoto.

Puedes solicitar la URL de la imagen asociada si llamas al método PlacePhoto.getUrl() y pasas 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.

El siguiente fragmento de código acepta un objeto de lugar y agrega un marcador al mapa si existe una foto. La imagen del marcador predeterminada 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 de fotos provienen de una variedad de ubicaciones, incluidos los propietarios de empresas y las fotos que aportan los usuarios. En la mayoría de los casos, estas fotos se pueden usar sin atribución o tendrán la atribución requerida incluida como parte de la imagen. Sin embargo, si el elemento photo que se muestra incluye un valor en el campo html_attributions, debes incluir la atribución adicional en tu aplicación en cualquier lugar en el que muestres la imagen.