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.
Círculo

Si seleccionas tu área geográfica como un círculo, debes proporcionar un center y un radius. El centro puede ser una latitud y longitud, o el ID de lugar del centro del círculo.

  • 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 lugar tienen una geometría bien definida y, en estos casos, la API de Places Insights muestra un código de error 404.

En la siguiente tabla, se enumeran los tipos de regiones no admitidos. Para determinar si un ID de lugar representa un tipo de región no compatible, pásalo en una solicitud a la API de Geocoding. La respuesta incluye el array type que enumera las regiones asociadas con el ID de lugar, como city, neighborhood o country.

Tipos de regiones no admitidos
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise
Á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 escribir 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. Además de las primeras y últimas coordenadas, no debe haber otras coordenadas duplicadas. Además, los bordes no adyacentes no se pueden cruzar, y tampoco se permiten bordes de 180 grados (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

Filtrar según el Estado actual (como en funcionamiento o cerrado temporalmente)

Nivel de precio

Filtra según el Nivel de precio (como gratuito, moderado o costoso).

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