Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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.

A API Places Aggregate 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 funcionamento, nível de preço e classificações.
Recuperar detalhes do lugar: receba 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 o seguinte:
- Á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 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 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 destes 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, será necessário fornecer um center e um radius. O center pode ser uma latitude e longitude ou o ID de 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 de lugar do centro do círculo. Somente lugares de ponto 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 representável por um polígono). Por exemplo, o ID de lugar de Tampa, na Flórida, é 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 que indica que a região não é aceita. Além disso, para regiões geográficas complexas, as otimizações de processamento interno podem levar a uma pequena superaproximação 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 disputadas são rejeitadas automaticamente para garantir a precisão e a neutralidade dos serviços do Google. As áreas disputadas são regiões com limites conflitantes ou reivindicações territoriais de diferentes países ou entidades. As fronteiras disputadas são exibidas 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.

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

Os tipos de lugar não aceitos incluem:

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

As 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, primeira e última) 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 antípodas).

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 tipos de lugar primários e secundários aceitos pela API Places Aggregate, consulte a Tabela A em Tipos de lugar da API Places (nova). É 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 lugar primários incluídos.
excludedPrimaryTypes: lista de tipos de lugar primários 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.

Observação:os filtros de tipo incluem automaticamente subtipos dos tipos especificados. Por exemplo, se você filtrar por gym, os resultados também vão incluir lugares categorizados nos subtipos, como yoga_studio.

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 é não filtrar (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 funcionamento como OPERATIONAL ou TEMPORARILY_CLOSED. O comportamento do filtro operatingStatus funciona da seguinte maneira:

Se nenhum filtro tiver sido fornecido, somente os lugares com um status de funcionamento de OPERATING_STATUS_OPERATIONAL serão incluídos nos resultados.
Se um ou mais filtros forem fornecidos, será necessário especificar valores de status de funcionamento 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 de nível de preço válidos 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, independentemente de terem 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 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. Esses dois campos são opcionais. Se forem omitidos, eles também vão incluir lugares que não têm uma 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 minRating precisa ser sempre menor ou igual ao valor maxRating. Se minRating for especificado como maior que maxRating, um erro INVALID_ARGUMENT será retornado.