Parâmetros de solicitação

Este documento descreve os parâmetros de solicitação da API Places Insights e inclui insights e práticas recomendadas para usar esse serviço.

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

  • Contar lugares: determine o número de lugares que correspondem a critérios específicos, como tipo de local, status de operação, nível de preço e classificações.
  • Extrair detalhes do lugar: receba os nomes dos lugares que atendem aos filtros especificados e, em seguida, busque informações mais detalhadas usando a 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 a API Places Insights. Cada solicitação precisa fornecer o seguinte:

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

Tipo de insight

Especifica o tipo de insights que você quer calcular. Os seguintes tipos de insight são aceitos:

  • 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 do filtro.

    Observação: se você selecionar INSIGHT_PLACES, a API Places Insights vai retornar os IDs de lugar apenas se o count for igual ou menor que 100.

Filtros

Especifica os critérios para filtrar lugares. No mínimo, é necessário especificar 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 centro e raio.
  • region: define uma área como uma região.
  • customArea: define uma área como um polígono personalizado.
Círculo

Se você selecionar sua área geográfica como um círculo, forneça um center e um radius. O centro pode ser uma latitude e uma longitude ou o ID do lugar do centro do círculo.

  • center:
    • latLng: latitude e longitude do centro do círculo. As latitudes precisam ser um número entre -90 e 90, inclusive. A longitude precisa ser um número entre -180 e 180.
    • place: o ID do lugar do centro do círculo. Somente lugares com pontos são aceitos. 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 transmitindo um ID de lugar para o parâmetro place. O ID do lugar representa uma área geográfica (como uma área que pode ser representada por um polígono). Por exemplo, o ID do lugar de Tampa, Flórida, é places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Nem todos os IDs de lugar têm uma geometria bem definida. Nesses casos, a API Places Insights retorna um código de erro 404.

A tabela a seguir lista os tipos de região não compatíveis. Para determinar se um ID de lugar representa um tipo de região sem suporte, transmita o ID de lugar em uma solicitação da API Geocoding. A resposta inclui a matriz type que lista as regiões associadas ao ID do lugar, como city, neighborhood ou country.

Tipos de região sem suporte
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 a área de um polígono personalizado usando coordenadas de latitude e longitude.

Acesse https://geojson.io/ para desenhar um polígono personalizado e insira essas coordenadas na solicitação. Um polígono precisa ter pelo menos quatro coordenadas, em que a primeira e a última são idênticas. Pelo menos três das coordenadas fornecidas precisam ser exclusivas. Além das coordenadas inicial e final, não pode haver outras coordenadas duplicadas. Além disso, as arestas não adjacentes não podem se cruzar, e as arestas de comprimento 180 graus não são permitidas, ou seja, vértices adjacentes não podem ser antipodais.

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 conferir uma lista de tipos de lugar principais e secundários compatíveis com a API Places Insights, consulte a Tabela A em Tipos de lugar para a API Places (novo). É necessário especificar pelo menos um tipo includedTypes ou includedPrimaryTypes.

  • includedTypes: lista de tipos de lugar incluídos.
  • excludedTypes: lista de tipos de lugar excluídos.
  • includedPrimaryTypes: lista de tipos de lugares principais incluídos.
  • excludedPrimaryTypes: lista de tipos de lugares principais excluídos.

Para saber mais sobre como os filtros de tipo e os tipos de lugar funcionam, consulte mais informações sobre filtros de tipo.

Parâmetros opcionais

Estes filtros são opcionais:

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

Status de funcionamento

Filtrar com base no status de operação (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 os lugares com base na classificação média dos usuários. Esses dois campos são opcionais. Se forem omitidos, eles vão incluir, por padrão, lugares que não têm uma classificação.

  • minRating: nota média mínima do usuário (entre 1,0 e 5,0).
  • maxRating: nota média máxima do usuário (entre 1,0 e 5,0).