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

Importante: a área de qualquer filtro de local precisa ter entre 1.556,86 metros quadrados (aproximadamente o tamanho de um quarteirão pequeno) e 2 trilhões de metros quadrados (aproximadamente o tamanho do Alasca). As solicitações com áreas fora desse intervalo vão retornar um erro INVALID_ARGUMENT.

Observação: para entidades com limites poligonais definidos, como parques ou aeroportos, a entidade é considerada dentro da área de pesquisa se qualquer parte do polígono se cruzar com a área de pesquisa definida (círculo, região ou polígono personalizado). O ponto central da entidade não precisa estar dentro da área de pesquisa.

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 a filtragem precisa e precisa 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. 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 de 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 400 com uma mensagem que indica que a região não tem suporte. Além disso, para regiões geográficas complexas, as otimizações de processamento interno podem levar a uma leve superestimativa da área (até 2 a 3%) que representa a região.

Importante:ao usar o filtro region com o tipo de insight INSIGHT_PLACES, as solicitações que incluem áreas contestadas são automaticamente rejeitadas para garantir a precisão e a neutralidade dos serviços do Google. Áreas disputadas são regiões com fronteiras conflitantes ou reivindicações territoriais de diferentes países ou entidades. Os limites contestados são mostrados como uma linha cinza tracejada no Google Maps.

Para mais informações sobre como as regiões disputadas são identificadas, consulte Entender as fronteiras e os nomes dos países.

Importante:o Google não oferece suporte a determinados IDs de lugar que pertencem aos seguintes tipos de região:

• Tipos de regiões tão grandes que resultam em alta latência.
• Tipos de região tão pequenos que comprometem a conformidade com a privacidade.

Para determinar se um ID de lugar representa um tipo de lugar sem suporte, transmita o ID do lugar 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 city, neighborhood ou country.

Os tipos de lugar não compatíveis incluem:

• establishment: geralmente indica um lugar que ainda não foi categorizado.
• street_number: indica o número exato da rua.
• floor: indica o andar de um edifício.
• post_box: indica uma caixa postal específica.
• street_address: indica um endereço preciso.
• room: indica a sala de um edifício.
• intersection: indica uma interseção principal, normalmente de duas estradas principais.
• landmark: indica um lugar por perto que é usado como referência para ajudar na navegação.
• subpremise: indica uma entidade endereçável abaixo do nível da premissa, como um apartamento, uma unidade ou um apartamento.
• sublocality_level_5: o nível granular mais específico dos componentes do endereço de sublocalidade, que normalmente representa uma subdivisão de bairro muito pequena ou uma área hiperlocal em uma cidade.

Área personalizada

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

Importante: as coordenadas que definem os vértices do polígono precisam ser listadas na ordem anti-horária. Isso segue a convenção padrão do setor para definir polígonos, em que a ordem anti-horária indica que o interior do polígono está à esquerda das bordas do limite.

Importante: as áreas personalizadas precisam ter 7.000 vértices ou menos.

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, em que a primeira e a última coordenadas são idênticas. Pelo menos três das coordenadas fornecidas precisam ser únicas.

Coordenadas idênticas consecutivas serão tratadas como uma única coordenada. No entanto, coordenadas duplicadas não consecutivas (exceto as coordenadas iniciais e finais idênticas necessárias) vão resultar em um erro.

Além disso, arestas não adjacentes não podem se cruzar, e arestas de 180 graus não são permitidas (ou seja, vértices adjacentes não podem ser antipópodais).

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 aceitos pela 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 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, é possível filtrar com base no status de operação, como OPERATIONAL ou TEMPORARILY_CLOSED. O comportamento do filtro operatingStatus funciona da seguinte maneira:

• Se nenhum filtro tiver sido fornecido, apenas os lugares com um status operacional de OPERATING_STATUS_OPERATIONAL serão incluídos nos resultados.
• Se um ou mais filtros forem fornecidos, você precisará especificar valores de status de operação válidos (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 do 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, mesmo que tenham um nível de preço atribuído. Isso inclui lugares sem informações de nível de preço, que podem não ser retornados ao filtrar por níveis de preço específicos.
• Se um ou mais filtros forem fornecidos:somente os lugares que corresponderem aos níveis de preço especificados serão retornados.

Filtro "Classificação"

Filtra lugares com base na nota 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).

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.