parámetros de solicitud

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.

Nota: Si seleccionas INSIGHT_PLACES, la API de Places Insights muestra los IDs de lugar solo si count es 100 o menos.

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.

Importante: El área de cualquier filtro de ubicación debe estar entre 1,556.86 metros cuadrados (aproximadamente el tamaño de un pequeño bloque de ciudad) y 2 billones de metros cuadrados (aproximadamente el tamaño de Alaska). Las solicitudes con áreas fuera de este rango mostrarán un error INVALID_ARGUMENT.

Nota: En el caso de las entidades con límites poligonales definidos, como parques o aeropuertos, se considera que la entidad se encuentra dentro del área de búsqueda si alguna parte de su polígono se cruza con el área de búsqueda definida (círculo, región o polígono personalizado). No es necesario que el punto central de la entidad esté dentro del área de búsqueda.

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 prefijo places/.
• 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.

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 neutralidad de los servicios de Google. Las áreas en disputa son regiones con límites en conflicto o reclamos territoriales 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.

Importante: Google no admite ciertos IDs de lugares que pertenecen a los siguientes tipos de regiones:

• Tipos de regiones que son tan grandes que generan una latencia alta.
• Tipos de regiones que son tan pequeños que comprometen el cumplimiento de la privacidad

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.

Importante: Las coordenadas que definen los vértices del polígono deben aparecer en orden en sentido contrario a las manecillas del reloj. Esto sigue la convención estándar de la industria para definir polígonos, en la que el orden en sentido contrario a las manecillas del reloj indica que el interior del polígono se encuentra a la izquierda de los bordes del límite.

Importante: Las áreas personalizadas deben tener 7,000 vértices o menos.

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 por operatingStatus: 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.