Parâmetros de solicitação

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

Com a API Places Aggregate, é possível 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 operacional, nível de preço e avaliações.
  • Recuperar detalhes do lugar: obtenha os nomes dos lugares que atendem aos filtros especificados e busque informações mais detalhadas usando a API Places.
  • Filtragem flexível: aplique filtros abrangentes para receber agregações precisas. 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 obrigatórios ao emitir uma solicitação para a API Places Aggregate. 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 insight que você quer calcular. Os seguintes tipos de insights são compatíveis:

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

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 um centro e um 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 center pode ser uma latitude e uma longitude ou o ID do lugar do centro do círculo. Esse método permite uma filtragem precisa e exata com base na região circular definida.

  • 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, inclusive.
    • place: ID do lugar do centro do círculo. Apenas lugares pontuais 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 ao parâmetro place. O ID de lugar representa uma área geográfica, como uma área representável por um polígono. Por exemplo, o ID do lugar de Tampa, FL é places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Nem todos os IDs de lugar têm uma geometria bem definida. Nesses casos, a API Places Aggregate retorna um código de erro 400 com uma mensagem indicando que a região não é compatível. Além disso, para regiões geográficas complexas, as otimizações de processamento interno podem levar a uma pequena superestimativa da área (até 2 a 3%) que representa a região.

Para determinar se um ID de lugar representa um tipo de lugar não compatível, transmita o ID em uma solicitação da API Geocoding. A resposta inclui a matriz type, que lista os tipos de lugar associados ao ID do lugar, como locality, neighborhood ou country. Um lugar será rejeitado para filtragem por região se qualquer um dos tipos dele corresponder a essa lista.

Tipos de lugar não aceitos:

  • establishment: geralmente indica um lugar que ainda não foi classificado.
  • intersection: indica uma interseção principal, normalmente de duas estradas principais.
  • subpremise: indica uma entidade endereçável abaixo do nível do imóvel, como um apartamento, uma unidade ou uma suíte.
Á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 inserir essas coordenadas na solicitação. Um polígono precisa ter pelo menos quatro coordenadas, sendo que a primeira e a última são idênticas. Pelo menos três das coordenadas fornecidas precisam ser únicas.

Coordenadas consecutivas idênticas serão tratadas como uma única coordenada. No entanto, coordenadas duplicadas não consecutivas (além das coordenadas idênticas necessárias) vão resultar em um erro.

Além disso, não é permitido que arestas não adjacentes se cruzem, e arestas de comprimento de 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 por tipo

Especifica os tipos de lugares a serem incluídos ou excluídos. Para conferir uma lista dos tipos de lugar primários e secundários compatíveis com a API Places Aggregate, consulte a Tabela A em Tipos de lugar na API Places (nova). É necessário especificar pelo menos um tipo de includedTypes ou includedPrimaryTypes.

  • includedTypes: lista de tipos de lugares incluídos.
  • excludedTypes: lista de tipos de lugares excluídos.
  • includedPrimaryTypes: lista de tipos de lugar 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 é a filtragem por operatingStatus: OPERATING_STATUS_OPERATIONAL (um valor específico).
  • priceLevels: especifica os níveis de preço dos lugares a serem incluídos. Por padrão, nenhuma filtragem de nível de preço é aplicada, e todos os lugares (incluindo aqueles sem informações de nível de preço) são retornados.
  • 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

Com o filtro operatingStatus, você pode filtrar com base no status operacional, como OPERATIONAL ou TEMPORARILY_CLOSED. O comportamento do filtro operatingStatus funciona da seguinte maneira:

  • Se nenhum filtro for fornecido, apenas lugares com status operacional OPERATING_STATUS_OPERATIONAL serão incluídos nos resultados.
  • Se um ou mais filtros forem fornecidos, especifique valores válidos de status operacional (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED ou OPERATING_STATUS_TEMPORARILY_CLOSED).

Nível de preço

Com o filtro priceLevels, é possível filtrar lugares com base no nível de preço. Os valores válidos de nível de preço são: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE e PRICE_LEVEL_VERY_EXPENSIVE.

O comportamento do filtro priceLevels é o seguinte:

  • Se nenhum filtro for fornecido:todos os lugares serão retornados, independente de terem um nível de preço atribuído. Isso inclui lugares sem informações de faixa de preço, que podem não ser retornados ao filtrar por faixas específicas.
  • Se um ou mais filtros forem fornecidos:somente os lugares que correspondem aos níveis de preço especificados serão retornados.

Filtro "Classificação"

Filtra lugares com base nas classificações médias dos usuários. Ambos os campos são opcionais. Se forem omitidos, o padrão será incluir lugares sem classificação.

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

Além disso, o valor de minRating precisa ser sempre menor ou igual ao valor de maxRating. Se minRating for especificado como maior que maxRating, um erro INVALID_ARGUMENT será retornado.