La API de Places Aggregate, antes conocida como API de Places Insights, ahora tiene disponibilidad general (GA).

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

parámetros de solicitud

En este documento, se describen los parámetros de la solicitud de la API de Places Aggregate y se incluyen estadísticas y prácticas recomendadas para usar este servicio.

La API de Places Aggregate te permite realizar varias funciones clave:

Contar lugares: Determina la cantidad de lugares que cumplen con criterios específicos, como el tipo de ubicación, el estado operativo, el nivel de precios y las calificaciones.
Recupera detalles de lugares: Obtén los nombres de los lugares que cumplen con los filtros especificados y, luego, recupera información más detallada con la API de Places.
Filtrado flexible: Aplica filtros integrales para obtener agregados precisos. Entre los filtros disponibles, se incluyen los siguientes:
- Área geográfica (círculo, región o polígono personalizado)
- Tipos de lugares
- Estado operativo
- Niveles de precios
- Rangos de clasificación

Parámetros obligatorios

En esta sección, se describen los parámetros obligatorios cuando se emite una solicitud a la API de Places Aggregate. Cada solicitud debe proporcionar lo siguiente:

Es un tipo de estadística.
Es un filtro de ubicación y un filtro de tipo.

Tipo de estadística

Especifica el tipo de estadísticas que deseas calcular. Se admiten los siguientes tipos de estadísticas:

INSIGHT_COUNT: Devuelve la cantidad de lugares que coinciden con los criterios de filtro.
INSIGHT_PLACES: Muestra los IDs de lugar que coinciden con los criterios de filtrado.

Filtros

Especifica los criterios para filtrar lugares. Como mínimo, debes especificar LocationFilter y TypeFilter.

Filtro de ubicación

Un filtro de ubicación puede tener uno de los siguientes tipos:

circle: Define un área como un círculo con un centro y un radio.
region: Define un área como una región.
customArea: Define un área como un polígono personalizado.

Círculo

Si seleccionas tu área geográfica como un círculo, debes proporcionar un center y un radius. El center puede ser una latitud y una longitud, o el ID de lugar del centro del círculo. Este método permite un filtrado preciso y exacto según la región circular que definiste.

center:
- latLng: Latitud y longitud del centro del círculo. Las latitudes deben ser un número entre -90 y 90, inclusive. La longitud debe ser un número entre -180 y 180, inclusive.
- place: Es el ID de lugar del centro del círculo. Ten en cuenta que solo se admiten lugares de puntos. Esta cadena debe comenzar con el prefijo places/.
radius: Radio del círculo en metros. Este número debe ser positivo.

Región

Define tu área como una región pasando un ID de lugar al parámetro place. El ID de lugar representa un área geográfica (como un área que se puede representar con un polígono). Por ejemplo, el ID de lugar de Tampa, Florida, es places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Ten en cuenta que no todos los IDs de lugar tienen una geometría bien definida y, en esos casos, la API de Places Aggregate devuelve un código de error 400 con un mensaje que indica que la región no es compatible. Además, en el caso de las regiones geográficas complejas, las optimizaciones del procesamiento interno pueden generar una ligera sobreestimación del área (hasta un 2 o 3%) que representa la región.

Importante: Cuando se usa el filtro region con el tipo de estadísticas INSIGHT_PLACES, las solicitudes que incluyen áreas en disputa se rechazan automáticamente para garantizar la precisión y la neutralidad de los servicios de Google. Las áreas en disputa son regiones con límites o reclamos territoriales en conflicto por parte de diferentes países o entidades. Los límites en disputa aparecen como una línea gris discontinua en Google Maps.

Para obtener más información sobre cómo se identifican las regiones en disputa, consulta Comprende las fronteras y los nombres de los países.

Para determinar si un ID de lugar representa un tipo de lugar no admitido, pasa el ID de lugar en una solicitud de la API de Geocoding. La respuesta incluye el array type, que enumera los tipos de lugar asociados con el ID de lugar, como locality, neighborhood o country. Se rechazará un lugar para el filtrado por región si alguno de sus tipos coincide con esta lista.

Entre los tipos de lugares no admitidos, se incluyen los siguientes:

establishment: Por lo general, indica un lugar que aún no se categorizó.
intersection: Indica una intersección principal, generalmente de dos rutas principales.
subpremise: Indica una entidad direccionable por debajo del nivel de la instalación, como un departamento, una unidad o una suite.

Área personalizada

Define el área de un polígono personalizado con coordenadas de latitud y longitud.

Puedes visitar https://geojson.io/ para dibujar un polígono personalizado y, luego, ingresar esas coordenadas en la solicitud. Un polígono debe tener, como mínimo, 4 coordenadas, en las que la primera y la última sean idénticas. Al menos 3 de las coordenadas proporcionadas deben ser únicas.

Las coordenadas idénticas consecutivas se tratarán como una sola coordenada. Sin embargo, las coordenadas duplicadas no consecutivas (que no sean las coordenadas idénticas primera y última requeridas) generarán un error.

Además, no se permite que los bordes no adyacentes se intersequen, y no se permiten bordes de 180 grados de longitud (es decir, los vértices adyacentes no pueden ser antípodas).

Por ejemplo:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

Filtro de tipo

Especifica los tipos de lugares que se incluirán o excluirán. Para obtener una lista de los tipos de lugares principales y secundarios que admite la API de Places Aggregate, consulta la Tabla A en Tipos de lugares de la API de Places (nuevo). Debes especificar al menos un tipo de includedTypes o includedPrimaryTypes.

includedTypes: Lista de tipos de lugares incluidos.
excludedTypes: Es la lista de tipos de lugares excluidos.
includedPrimaryTypes: Es la lista de tipos de lugares principales incluidos.
excludedPrimaryTypes: Es la lista de tipos de lugares principales excluidos.

Para obtener más información sobre cómo funcionan los filtros de tipo y los tipos de lugares, consulta más información sobre los filtros de tipo.

Parámetros opcionales

Estos filtros son opcionales:

operatingStatus: Especifica los estados de los lugares que se incluirán o excluirán. De forma predeterminada, se filtra por operatingStatus: OPERATING_STATUS_OPERATIONAL (un valor específico).
priceLevels: Especifica los niveles de precios de los lugares que se incluirán. De forma predeterminada, no se aplica ningún filtro de nivel de precios y se muestran todos los lugares (incluidos aquellos sin información de nivel de precios).
ratingFilter: Especifica el rango de clasificación de los lugares. El valor predeterminado es sin filtrado (todas las calificaciones se incluyen en los resultados).

Estado operativo

Con el filtro operatingStatus, puedes filtrar según el Estado operativo, como OPERATIONAL o TEMPORARILY_CLOSED. El comportamiento del filtro operatingStatus funciona de la siguiente manera:

Si no se proporcionaron filtros, solo se incluirán en los resultados los lugares con un estado operativo de OPERATING_STATUS_OPERATIONAL.
Si se proporcionan uno o más filtros, debes especificar valores de estado operativo válidos (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED o OPERATING_STATUS_TEMPORARILY_CLOSED).

Nivel de precio

Con el filtro priceLevels, puedes filtrar lugares según su nivel de precios. Los valores válidos del nivel de precios son PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE y PRICE_LEVEL_VERY_EXPENSIVE.

El comportamiento del filtro priceLevels es el siguiente:

Si no se proporcionan filtros: Se devuelven todos los lugares, independientemente de si tienen un nivel de precios asignado. Esto incluye los lugares sin información sobre el nivel de precios, que es posible que no se muestren cuando se filtran por niveles de precios específicos.
Si se proporcionan uno o más filtros: Solo se muestran los lugares que coinciden con los niveles de precios especificados.

Filtro de clasificación

Filtra los lugares según las calificaciones promedio de los usuarios. Ambos campos son opcionales, por lo que, si se omiten, se incluirán de forma predeterminada los lugares que no tengan una calificación.

minRating: Calificación promedio mínima del usuario (entre 1.0 y 5.0).
maxRating: Calificación promedio máxima del usuario (entre 1.0 y 5.0).

Además, el valor de minRating siempre debe ser menor o igual que el valor de maxRating. Si se especifica que minRating es mayor que maxRating, se mostrará un error de INVALID_ARGUMENT.