En este documento, se describen los parámetros de solicitud de la API de Places Insights y se incluyen estadísticas y prácticas recomendadas para usar este servicio.
La API de Places Insights te permite realizar varias funciones clave:
- Cantidad de lugares: Determina la cantidad de lugares que coinciden con criterios específicos, como el tipo de ubicación, el estado de funcionamiento, el nivel de precios y las calificaciones.
- Cómo recuperar 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 integrales para obtener estadísticas 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 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 Insights. 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ísticas que deseas calcular. Se admiten los siguientes tipos de estadísticas:
INSIGHT_COUNT
: Muestra la cantidad de lugares que coinciden con los criterios del filtro.INSIGHT_PLACES
: Muestra los IDs de lugares que coinciden con los criterios del 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
. center
puede ser una latitud y longitud, o el ID de Place del centro del círculo. Este método permite un filtrado preciso 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 del lugar del centro del círculo. Ten en cuenta que solo se admiten lugares de punto. Esta cadena debe comenzar con el prefijoplaces/
.
radius
: Es el radio del círculo en metros. Este número debe ser positivo.
Región
Para definir tu área como una región, pasa 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 Place tienen una geometría bien definida y, en estos casos, la API de Places Insights muestra 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 de procesamiento interno pueden generar una ligera sobreestimación del área (hasta un 2 o 3%) que representa la región.
Para determinar si un ID de lugar representa un tipo de lugar no compatible, pasa el ID de lugar en una solicitud a la API de Geocoding. La respuesta incluye el array type
, que enumera los tipos de lugares asociados con el ID de lugar, como city
, neighborhood
o country
.
Entre los tipos de lugares no admitidos, se incluyen los siguientes:
establishment
suele indicar un lugar que aún no se categorizó.street_number
: Indica el número exacto de una calle.floor
: Indica el piso de la dirección de un edificio.post_box
: Indica una casilla de correo postal específica.street_address
: Indica una dirección precisa.room
: Indica una habitación en una dirección de un edificio.intersection
: Indica una intersección principal, generalmente de dos rutas principales.landmark
: Indica un lugar cercano que se usa como referencia para facilitar la navegación.subpremise
: Indica una entidad direccionable por debajo del nivel de la premisa, como un departamento, una unidad o un departamento en suite.sublocality_level_5
: Es el nivel de detalle más específico de los componentes de la dirección de sublocalidad, que suele representar una subdivisión de vecindario muy pequeña o un área hiperlocal dentro de una ciudad.
Á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 (excepto las primeras y últimas coordenadas idénticas requeridas) generarán un error.
Además, no se permite que los bordes no adyacentes se intersequen, ni que los bordes de 180 grados de longitud (es decir, los vértices adyacentes no pueden ser antipodales).
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 lugares principales y secundarios que admite la API de Places Insights, consulta la Tabla A en Tipos de lugares de 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 los tipos de lugares principales incluidos.excludedPrimaryTypes
: Es una lista de los 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. La configuración predeterminada es filtrar poroperatingStatus: OPERATING_STATUS_OPERATIONAL
(un valor específico).priceLevels
: Especifica los niveles de precios de los lugares. El valor predeterminado es no filtrar (todos los niveles de precios se incluyen en los resultados).ratingFilter
: Especifica el rango de calificación de los lugares. El valor predeterminado es no filtrar (todas las calificaciones se incluyen en los resultados).
Estado operativo
Con el filtro operatingStatus
, puedes filtrar según el Estado operativo (como en funcionamiento o cerrado temporalmente). Si no se configura el filtro operatingStatus
, solo se incluyen en los resultados los lugares con un estado operativo de OPERATING_STATUS_OPERATIONAL
.
Nivel de precio
Con el filtro price_levels
, puedes filtrar según el nivel de precio (como gratuito, moderado o costoso). Si no se establece el filtro price_levels
, todos los niveles de precio se incluyen en los resultados.
Filtro de clasificación
Filtra los lugares según sus calificaciones promedio de los usuarios. Ambos campos son opcionales, por lo que, si se omiten, se incluirán de forma predeterminada lugares que no tienen 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 de INVALID_ARGUMENT
.