Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

parámetros de solicitud

En este documento, se describen los parámetros de 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:

Recuento de lugares: Determina la cantidad de lugares que coinciden con criterios específicos, como el tipo de ubicación, el estado operativo, el nivel de precios y las calificaciones.
Recupera detalles de un lugar: 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 completos para obtener agregaciones precisas. 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 calificaciones

Parámetros obligatorios

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

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

Tipo de estadística

Especifica el tipo de estadística 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: Devuelve los IDs de lugar que coinciden con los criterios de filtro.

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 definas.

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: Es el 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 estos casos, la API de Places Aggregate devuelve un código de error 400 con un mensaje que indica que no se admite la región. Además, en el caso de las regiones geográficas complejas, las optimizaciones de procesamiento interno pueden generar una ligera sobreaproximación del área (hasta un 2% o 3%) que representa la región.

Importante: Cuando usas el filtro region con el tipo de estadística INSIGHT_PLACES, las solicitudes que incluyen áreas en disputa se rechazan automáticamente para garantizar la exactitud y neutralidad de los servicios de Google. Las áreas en disputa son regiones con límites o reclamos territoriales en conflicto entre diferentes países o entidades. Los límites en disputa se muestran 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 Información sobre los nombres y las fronteras 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 a la API de Geocoding. La respuesta incluye el array type, en el que se enumeran 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 cualquiera de sus tipos coincide con esta lista.

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

establishment: suele indicar 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 premisa, 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 primeras y últimas coordenadas idénticas requeridas) generarán un error.

Además, no se permite que se crucen los bordes no adyacentes ni que haya 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 deben incluir o excluir. Para obtener una lista de los tipos de lugar principales y secundarios que admite la API de Places Aggregate, consulta la Tabla A en Tipos de lugar para la API de Places (nueva). Debes especificar al menos un tipo includedTypes o includedPrimaryTypes.

includedTypes: Es la 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 lugar, consulta más información sobre los filtros de tipo.

Nota: Los filtros de tipo incluyen automáticamente subtipos de los tipos especificados. Por ejemplo, si filtras por gym, los resultados también incluirán lugares que se clasifican en sus subtipos, como yoga_studio.

Parámetros opcionales

Estos filtros son opcionales:

operatingStatus: Especifica los estados de los lugares que se deben incluir o excluir. 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 devuelven todos los lugares (incluidos aquellos que no tienen información sobre el nivel de precios).
ratingFilter: Especifica el rango de calificaciones de los lugares. De forma predeterminada, no se aplica ningún filtro (se incluyen todas las calificaciones 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 podrían no mostrarse cuando se filtra por niveles de precios específicos.
Si se proporcionan uno o más filtros, solo se devuelven 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: Es la calificación promedio mínima de los usuarios (entre 1.0 y 5.0).
maxRating: Es la calificación promedio máxima de los usuarios (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 muestra un error INVALID_ARGUMENT.