Parâmetros de solicitação

Este documento fornece uma visão geral clara de todos os parâmetros no API Places Insights. Abordaremos cada um deles em detalhes, oferecendo insights e as melhores práticas para ajudá-lo a usar essa ferramenta para suas necessidades de dados geográficos.

A API Places Insights permite executar várias funções importantes:

  • Contar casas: determine o número de casas que correspondem a critérios específicos. como tipo de local, status de funcionamento, nível de preço e classificações.
  • Recuperar detalhes do lugar: acesse os nomes dos lugares que atendem aos filtros especificados e buscar informações mais detalhadas usando o método API Places.
  • Filtragem flexível: aplique filtros abrangentes para receber insights precisos. Os filtros disponíveis incluem:
    • Área geográfica (círculo, região ou polígono personalizado)
    • Tipos de lugar
    • Status de funcionamento
    • Níveis de preço
    • Intervalos de classificação

Parâmetros obrigatórios

Esta seção aborda os parâmetros necessários ao emitir uma solicitação para o API Places Insights. Cada solicitação precisa fornecer o seguinte:

  • Um tipo de insight.
  • Um filtro de local e de tipo.

Insight

Especifica o tipo de insights que você quer computar. Os seguintes tipos de insight têm suporte:

  • INSIGHT_COUNT: retorna o número de lugares que correspondem aos critérios de filtro.
  • INSIGHT_PLACES: retorna os IDs de lugar que correspondem aos critérios de filtro.

Observação: se essa opção for selecionada, a API Places Insights vai retornar IDs de lugares. somente se count for 100 ou menos.

Filtro

Especifica os critérios para filtrar lugares. No mínimo, você deve especificar o LocationFilter e TypeFilter.

Filtro de local

Um filtro de local pode ter um dos seguintes tipos:

  • circle: define uma área como um círculo com um centro e um raio.
  • region: define uma área como uma região.
  • custom_area: define uma área como um polígono personalizado.
Círculo

Se você selecionar a área geográfica como um círculo, precisará informar um center e um radius. O centro pode ser a latitude e a longitude, ou o nome ID do centro do círculo.

  • central:
    • lat_lng: latitude e longitude do centro do círculo. Latitudes deve ser um número entre -90 e 90. A longitude precisa ser um número entre -180 e 180.
    • place: ID de lugar do centro do círculo. Observe que somente pontos suporte a lugares. Essa string precisa começar com o prefixo places/.
  • radius: raio do círculo em metros. Esse número precisa ser positivo.
Região

Defina sua área como uma região usando o parâmetro place. Usar um ID de lugar que representa uma área geográfica (como uma área que pode ser representada por um polígono). Por exemplo, o ID de lugar de Tampa, FL é places/ChIJ4dG5s4K3wogRY7SWr4kTX6c:

Tipos de região não compatíveis
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

É possível usar o campo types de uma chamada da API Geocoding para determinar a tipo de local ou endereço associado a um ID de lugar, por exemplo, se é um cidade, bairro ou país.

Área personalizada

Define a área de um polígono personalizado usando coordenadas.

Acesse https://geojson.io/ para desenhar um polígono personalizado e insira essas coordenadas na solicitação. Um polígono precisa ter pelo menos 4 coordenadas, em que a primeira e a última coordenadas são idênticas. Além do campo primeira e última coordenada, não deve haver nenhuma outra coordenada duplicada. Exemplo:

"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 os tipos de lugares a serem incluídos ou excluídos. Para uma lista de registros e secundários compatíveis com a API Places Insights, consulte a Tabela A no guia Tipos de local da API Places (novo). Pelo menos um tipo included_types ou included_primary_types precisa ser incluída.

  • included_types: lista de tipos de lugar incluídos.
  • excluded_types: lista de tipos de lugar excluídos.
  • included_primary_types: lista de tipos de lugares principais incluídos.
  • excluded_primary_types: lista de tipos de lugar principais excluídos.

Para saber mais sobre como funcionam os filtros de tipo e os tipos de lugar, acesse mais sobre tipos filtros.

Parâmetros opcionais

Os três filtros restantes são opcionais:

  • operating_status: especifica o status dos lugares a serem incluídos ou excluídos. O padrão é filtrar por operating_status: OPERATING_STATUS_OPERATIONAL (um valor específico).
  • price_levels: especifica os níveis de preço dos lugares. O padrão é "não" (todos os níveis de preços estão incluídos nos resultados).
  • rating_filter: especifica o intervalo de notas dos lugares. O padrão é "não" filtragem (todas as classificações estão incluídas nos resultados).

Status de funcionamento

Filtre com base no status de funcionamento (como operacional ou temporariamente fechado).

Nível de preço

Filtre com base no nível de preço (como sem custo financeiro, moderado ou caro).

Filtro "Classificação"

Filtra lugares com base nas avaliações médias dos usuários. Esses dois campos são opcionais. Portanto, se forem omitidos, o padrão também incluirá lugares que não têm uma classificação.

  • min_rating: avaliação média mínima de usuários (entre 1,0 e 5,0).
  • max_rating: é a nota média máxima dos usuários (entre 1,0 e 5,0).