API › Location › Aglomerações Comerciais

# Aglomerações Comerciais

Polígonos de tecido comercial denso do Brasil com quantidade de PDV, vocação, porte, faixa de renda e score — para decisões de expansão, escolha de ponto e enriquecimento de carteira de PDVs. 

Categoria Location

Cobertura ~11 mil aglomerações no Brasil

Fontes PrismaData (curadoria proprietária)

Geometria GeoJSON / WKT (SRID 4326)

Nesta página

Aplicações Conceito Convenção de sinais Entradas Exemplos Atributos retornados Detalhes técnicos Limitações

Para que serve

## Aplicações

O dado de aglomerações comerciais mapeia os polígonos de tecido comercial denso do Brasil e retorna, para cada aglomeração, sua vocação (moda, alimentação, varejo…), porte, faixa de renda, quantidade de PDVs, densidade por km² e score ponderado — sinais essenciais para expansão de rede, escolha de ponto, dimensionamento de catchment e enriquecimento de carteira. 

#### Expansão e Escolha de Ponto

Classifique candidatos a novos PDVs pelo porte, vocação e score da aglomeração em que estão inseridos ou pela distância à aglomeração mais próxima.

#### Catchment Area

Delimite áreas de influência com base no polígono da aglomeração e nos rankings municipal, estadual e nacional por PDVs, score e densidade.

#### Enriquecimento de Carteira

Marque cada PDV da sua base com o hash da aglomeração, vocação, faixa de renda e percentil nacional para segmentação e modelagem.

#### Vocação e Mix Territorial

Analise o mix de segmentos (moda, alimentação, saúde, eletrônicos…) por região para decisões de sortimento, preço e comunicação.

Entendendo o dado

## Conceito

Uma aglomeração comercial é um polígono derivado da concentração de pontos de venda (PDVs) em uma área contínua. Cada polígono agrega métricas territoriais (área, densidade de PDVs por km², renda mediana, percentil nacional de renda) e classificações discretas — **porte** (Pequena, Media, Grande), **concentracao** (Esparsa, Distribuida, Densa) e **faixa_renda** (Popular, Econômica, Intermediária, Premium, Luxo). 

A cada aglomeração são atribuídos rankings **nacional, estadual e municipal** por três critérios (PDVs, score ponderado e densidade), além de um perfil de **vocação** composto pelos percentuais de cada segmento (alimentação, moda, supermercado, saúde, construção, eletrônicos, móveis, combustíveis, automotivo, entretenimento, alojamento e varejo geral). O consumo se dá por proximidade (lat/lng), por endereço/trecho de rua, por busca com filtros ou por lookup direto pelo hash da aglomeração. 

Interpretação

## Convenção de Sinais

O campo booleano `dentro_de_aglomeracao` indica se o ponto consultado está contido em algum polígono. O campo numérico `densidade_pdvs_km2` quantifica a intensidade do tecido comercial da aglomeração retornada. 

●

**dentro_de_aglomeracao: true** O ponto está dentro do polígono de uma aglomeração — o hash retornado em `aglomeracao_hash_contendo` aponta para essa aglomeração.

○

**dentro_de_aglomeracao: false** O ponto está fora de qualquer polígono. Ainda assim, a aglomeração mais próxima dentro do raio pesquisado é retornada com `distancia_m` em metros.

●

**densidade_pdvs_km2 alta ( > 10.000)** Tecido comercial extremamente denso — típico de eixos consolidados (ex.: Avenida Paulista atinge ~50.625 PDVs/km²).

○

**densidade_pdvs_km2 baixa** Aglomeração esparsa ou de pequeno porte — combine com `porte` e `concentracao` para interpretar.

Request

## Parâmetros de Entrada

A família de endpoints de Aglomerações Comerciais oferece cinco formas de consumo, cobrindo desde consultas por ponto geográfico até rankings agregados. 

### `GET /location/commercial_cluster` — por lat/lng

Retorna a aglomeração mais próxima (ou top-N) de um ponto geográfico, opcionalmente com o trecho de rua mais próximo e o polígono da geometria.

`lat` float · obrigatório

Latitude WGS84 do ponto (-90 < lat < 90).

`lng` float · obrigatório

Longitude WGS84 do ponto (-180 < lng < 180).

`top_n` int · default 1

Quantidade de aglomerações a retornar (1 a 10). Quando >1, cada aglomeração vem prefixada com `1_`, `2_`…

`raio_km` float · default 5.0

Raio de busca em quilômetros (máx. 50).

`incluir_trecho_mais_proximo` bool · default true

Retorna também o trecho de rua mais próximo do ponto consultado.

`incluir_trechos_da_aglomeracao` bool · default false

Retorna todos os trechos de rua da aglomeração contendo o ponto.

`incluir_geometria` bool · default false

Retorna o polígono da aglomeração. Requer role `admin` ou `viewer:commercial_cluster` no JWT.

`wkt` bool · default false

Quando `incluir_geometria=true`, devolve a geometria em WKT em vez de GeoJSON.

`vocacao` array<string> · opcional

Filtra por vocações específicas (ex.: Moda, Alimentacao, Diversificada).

`porte_minimo` string · opcional

Porte mínimo aceito: `Pequena`, `Media` ou `Grande`.

`faixa_renda` array<string> · opcional

Uma ou mais faixas: `Popular`, `Econômica`, `Intermediária`, `Premium`, `Luxo`.

`versao_dados` string · opcional

Congela o retorno em uma versão específica da base (default: última disponível).

### `GET /location/commercial_cluster/street` — por trecho de rua

Retorna o(s) trecho(s) de rua mais próximo(s) de um ponto, com atributos da aglomeração-mãe opcionalmente incluídos.

`lat` float · obrigatório

Latitude WGS84 do ponto.

`lng` float · obrigatório

Longitude WGS84 do ponto.

`top_n` int · default 1

Quantidade de trechos a retornar (1 a 10).

`raio_m` float · default 200

Raio de busca em metros (máx. 5.000).

`incluir_aglomeracao` bool · default true

Inclui campos da aglomeração-mãe (nome, vocação, porte, faixa de renda…) no top-level.

`versao_dados` string · opcional

Versão da base a consultar.

### `POST /location/commercial_cluster/search` — busca por filtros

Busca aglomerações sem ponto geográfico, aplicando filtros por UF, município, vocação, porte, faixa de renda, quantidade de PDVs, score e bbox.

`filtros.uf` array<string>

Uma ou mais UFs (siglas de 2 caracteres).

`filtros.municipio` array<string>

Uma ou mais cidades (maiúsculas, sem acento).

`filtros.vocacao` array/string

Filtra por vocação (ex.: Moda, Diversificada, Alimentacao).

`filtros.porte` array<string>

Um ou mais portes: `Pequena`, `Media`, `Grande`.

`filtros.faixa_renda` array<string>

Uma ou mais faixas de renda.

`filtros.qtd_pdvs_min / qtd_pdvs_max` int

Intervalo de PDVs por aglomeração.

`filtros.score_min / score_max` float

Intervalo do score ponderado.

`filtros.bbox` objeto

Bounding box com `min_lat, min_lng, max_lat, max_lng`.

`ordenar_por` string · default score_ponderado

Campo de ordenação do resultado.

`ordem` string · default desc

`asc` ou `desc`.

`limite` int · default 50

Máximo de itens por página (1 a 200).

`offset` int · default 0

Deslocamento para paginação.

### `GET /location/commercial_cluster/ranking` — top-N por critério e escopo

Retorna as top-N aglomerações classificadas por score, quantidade de PDVs ou densidade — em escopo nacional, estadual ou municipal.

`criterio` string · default score

Critério de ordenação: `score`, `pdvs` ou `densidade`.

`escopo` string · default nacional

Universo do ranking: `nacional`, `uf` ou `municipio`.

`top_n` int · default 50

Quantidade de aglomerações no ranking (1 a 500).

`uf` string · opcional

Obrigatório quando `escopo=uf` ou `escopo=municipio`.

`municipio` string · opcional

Obrigatório quando `escopo=municipio`.

`vocacao` string · opcional

Restringe o ranking a uma vocação específica.

### `GET /location/commercial_cluster/{aglomeracao_hash}` — lookup direto pelo hash

Retorna todos os atributos de uma aglomeração conhecida e, opcionalmente, seus trechos de rua e a geometria do polígono.

`aglomeracao_hash` string · path · obrigatório

Identificador global da aglomeração (retornado pelos demais endpoints).

`incluir_trechos` bool · default true

Inclui todos os trechos de rua pertencentes à aglomeração.

`incluir_geometria` bool · default false

Requer role `admin` ou `viewer:commercial_cluster`.

`wkt` bool · default false

Formato WKT em vez de GeoJSON quando `incluir_geometria=true`.

### `POST /location/commercial_cluster/batch` — em lote

Processa até 1.024 pontos em uma única chamada, cada um identificado por `id_externo`. Aceita os mesmos parâmetros do endpoint por lat/lng (exceto `incluir_trechos_da_aglomeracao`). O campo `geometria` não é suportado em `/batch`.

`pontos[].id_externo` string · obrigatório

Identificador do ponto no seu sistema (retornado no output para correlação).

`pontos[].latitude / longitude` float · obrigatório

Coordenadas WGS84 do ponto.

`top_n_por_ponto` int · default 1

Aglomerações por ponto (1 a 10).

`raio_km` float · default 2.0

Raio de busca em quilômetros (máx. 50).

`incluir_trecho_mais_proximo` bool · default true

Retorna também o trecho de rua mais próximo de cada ponto.

Na prática

## Exemplos

Dois cenários em São Paulo ilustram o retorno do endpoint `/location/commercial_cluster`: um ponto dentro da Avenida Paulista e outro fora, em zona residencial. 

Ponto dentro de aglomeração (Av. Paulista) -23.5613, -46.6558

![Mapa: polígono da aglomeração da Av. Paulista com o ponto consultado dentro](https://prismadata.io/imagens/aglomeracoes/paulista_dentro.png)
    
    
    {
      "prismadata__commercial_cluster__latitude": -23.5613,
      "prismadata__commercial_cluster__longitude": -46.6558,
      "prismadata__commercial_cluster__dentro_de_aglomeracao": true,
      "prismadata__commercial_cluster__aglomeracao_hash_contendo": "5ebd0eb4f6b4",
      "prismadata__commercial_cluster__aglomeracao_hash": "5ebd0eb4f6b4",
      "prismadata__commercial_cluster__nome_aglomeracao": "Avenida Paulista / Alameda Ministro Rocha Azevedo - SAO PAULO/SP",
      "prismadata__commercial_cluster__municipio": "SAO PAULO",
      "prismadata__commercial_cluster__uf": "SP",
      "prismadata__commercial_cluster__qtd_pdvs": 5117,
      "prismadata__commercial_cluster__score_ponderado": 6402.5,
      "prismadata__commercial_cluster__area_ha": 10.11,
      "prismadata__commercial_cluster__densidade_pdvs_km2": 50625.8,
      "prismadata__commercial_cluster__centroide_lat": -23.561411,
      "prismadata__commercial_cluster__centroide_lng": -46.656262,
      "prismadata__commercial_cluster__porte": "Grande",
      "prismadata__commercial_cluster__concentracao": "Densa",
      "prismadata__commercial_cluster__faixa_renda": "Luxo",
      "prismadata__commercial_cluster__vocacao": "Diversificada",
      "prismadata__commercial_cluster__nome_segmento": "Grande, Densa, Luxo de Diversificada",
      "prismadata__commercial_cluster__pct_alimentacao": 8.8,
      "prismadata__commercial_cluster__pct_moda": 10.9,
      "prismadata__commercial_cluster__pct_eletronicos": 16.4,
      "prismadata__commercial_cluster__pct_varejo_geral": 12.6,
      "prismadata__commercial_cluster__renda_mediana": 8503.98,
      "prismadata__commercial_cluster__percentil_br_renda": 99.3,
      "prismadata__commercial_cluster__rank_nacional_score": 1,
      "prismadata__commercial_cluster__rank_nacional_pdvs": 1,
      "prismadata__commercial_cluster__rank_uf_score": 1,
      "prismadata__commercial_cluster__rank_municipal_score": 1,
      "prismadata__commercial_cluster__distancia_m": 0.0,
      "prismadata__commercial_cluster__distancia_borda_m": 57.99,
      "prismadata__commercial_cluster__contido": true
    }

O ponto está **dentro** da aglomeração (`dentro_de_aglomeracao: true`). Trata-se do polígono nº 1 do Brasil por score e PDVs — Grande porte, Densa, faixa de renda Luxo, com 5.117 PDVs e densidade de ~50.625 PDVs/km². O mix é Diversificado, com destaque para Eletrônicos (16,4%) e Varejo Geral (12,6%). 

Ponto fora de qualquer aglomeração (zona residencial) -23.6100, -46.7200

![Mapa: ponto acima da aglomeração de Paraisópolis, fora do polígono](https://prismadata.io/imagens/aglomeracoes/paraisopolis_fora.png)
    
    
    {
      "prismadata__commercial_cluster__latitude": -23.6100,
      "prismadata__commercial_cluster__longitude": -46.7200,
      "prismadata__commercial_cluster__dentro_de_aglomeracao": false,
      "prismadata__commercial_cluster__aglomeracao_hash_contendo": null,
      "prismadata__commercial_cluster__aglomeracao_hash": "a91c3f7b8e02",
      "prismadata__commercial_cluster__nome_aglomeracao": "Avenida Giovanni Gronchi - SAO PAULO/SP",
      "prismadata__commercial_cluster__municipio": "SAO PAULO",
      "prismadata__commercial_cluster__uf": "SP",
      "prismadata__commercial_cluster__qtd_pdvs": 312,
      "prismadata__commercial_cluster__score_ponderado": 418.7,
      "prismadata__commercial_cluster__area_ha": 4.82,
      "prismadata__commercial_cluster__densidade_pdvs_km2": 6473.0,
      "prismadata__commercial_cluster__porte": "Media",
      "prismadata__commercial_cluster__concentracao": "Distribuida",
      "prismadata__commercial_cluster__faixa_renda": "Premium",
      "prismadata__commercial_cluster__vocacao": "Alimentacao",
      "prismadata__commercial_cluster__renda_mediana": 5210.44,
      "prismadata__commercial_cluster__percentil_br_renda": 94.1,
      "prismadata__commercial_cluster__rank_nacional_score": 812,
      "prismadata__commercial_cluster__rank_uf_score": 187,
      "prismadata__commercial_cluster__rank_municipal_score": 96,
      "prismadata__commercial_cluster__distancia_m": 742.8,
      "prismadata__commercial_cluster__distancia_borda_m": 742.8,
      "prismadata__commercial_cluster__contido": false
    }

O ponto está **fora** de qualquer aglomeração (`dentro_de_aglomeracao: false`, `aglomeracao_hash_contendo: null`). A aglomeração mais próxima dentro do raio de 5 km está a 742 m — um polígono de porte Média, vocação Alimentação e faixa de renda Premium. 

Response

## Atributos Retornados

Todos os campos são retornados com o prefixo `prismadata__commercial_cluster__` (omitido nas tabelas abaixo por brevidade). Para `top_n > 1`, cada aglomeração vem prefixada com `1_`, `2_`, etc. 

Identificação

aglomeracao_hash

Identificador global da aglomeração retornada (hash estável entre versões).

aglomeracao_hash_contendo

Hash da aglomeração que _contém_ o ponto consultado; `null` quando o ponto está fora de qualquer polígono.

nome_aglomeracao

Nome descritivo da aglomeração (geralmente o eixo/rua principal seguido de município e UF).

nome_segmento

Rótulo textual combinando porte, concentração, faixa de renda e vocação (ex.: "Grande, Densa, Luxo de Diversificada").

municipio

Município da aglomeração (maiúsculas, sem acento).

uf

Unidade Federativa em 2 caracteres (ex.: SP, RJ).

Localização e Distância

latitude / longitude

Coordenadas do ponto consultado (eco do input).

dentro_de_aglomeracao

Booleano — `true` quando o ponto está dentro de algum polígono da base.

contido

Se o ponto consultado está dentro do polígono da aglomeração retornada.

distancia_m

Distância em metros do ponto até a aglomeração retornada (0 quando o ponto está dentro).

distancia_borda_m

Distância em metros do ponto até a borda do polígono.

centroide_lat / centroide_lng

Coordenadas do centroide do polígono da aglomeração.

area_ha

Área do polígono em hectares.

Classificação

porte

Enum: `Pequena`, `Media` ou `Grande`.

concentracao

Enum: `Esparsa`, `Distribuida` ou `Densa`.

faixa_renda

Enum: `Popular`, `Econômica`, `Intermediária`, `Premium` ou `Luxo`.

vocacao

Vocação predominante da aglomeração (ex.: Diversificada, Moda, Alimentacao, Automotivo).

renda_mediana

Renda mensal mediana da área da aglomeração, em reais.

percentil_br_renda

Percentil da renda mediana em relação ao Brasil (0 a 100).

Métricas de Volume

qtd_pdvs

Quantidade absoluta de PDVs na aglomeração.

densidade_pdvs_km2

Densidade de PDVs por quilômetro quadrado.

score_ponderado

Score composto de atratividade comercial (combina PDVs, densidade e renda).

Mix por Segmento (pct_*)

pct_alimentacao

Percentual dos PDVs classificados no segmento de alimentação (bares, restaurantes, lanchonetes).

pct_moda

Percentual dos PDVs de vestuário, calçados e acessórios.

pct_supermercado

Percentual de supermercados e mercearias.

pct_saude

Percentual de farmácias, clínicas e serviços de saúde.

pct_construcao

Percentual de materiais de construção.

pct_eletronicos

Percentual de eletrônicos e eletrodomésticos.

pct_moveis

Percentual de móveis e decoração.

pct_combustiveis

Percentual de postos e distribuidoras de combustíveis.

pct_automotivo

Percentual de PDVs do setor automotivo (concessionárias, autopeças, oficinas).

pct_entretenimento

Percentual de cinemas, casas de shows, bares e afins.

pct_alojamento

Percentual de hotéis, pousadas e hostels.

pct_varejo_geral

Percentual de varejo geral não classificado nas categorias anteriores.

Rankings

rank_nacional_pdvs / rank_nacional_score / rank_nacional_densidade

Posição da aglomeração no ranking nacional por PDVs, score ponderado e densidade.

rank_uf_pdvs / rank_uf_score / rank_uf_densidade

Posição da aglomeração no ranking da UF (Unidade Federativa) pelos mesmos três critérios.

rank_municipal_pdvs / rank_municipal_score / rank_municipal_densidade

Posição da aglomeração no ranking do município.

Trecho de Rua (opt-in via incluir_trecho_mais_proximo)

trecho_hash

Identificador do trecho de rua mais próximo do ponto.

trecho_aglomeracao_hash

Hash da aglomeração à qual o trecho pertence (pode ser diferente da aglomeração principal retornada).

trecho_logradouro / trecho_tipo_via

Nome do logradouro e tipo de via (AVENIDA, RUA, TRAVESSA…).

trecho_num_inicial / trecho_num_final

Numeração aproximada dos limites do trecho (podem ser `null`).

trecho_extensao_m / trecho_n_esquinas / trecho_buffer_m

Extensão do trecho em metros, número de esquinas cobertas e largura de buffer aplicada.

trecho_qtd_pdvs / trecho_score_ponderado / trecho_densidade_linear_km

Métricas do trecho: PDVs, score e densidade linear por quilômetro de calçada.

trecho_distancia_m

Distância em metros do ponto consultado até o trecho.

trecho_rank_nacional_score / trecho_rank_uf_score / trecho_rank_municipal_score / trecho_rank_aglomeracao_score

Rankings do trecho por score (nacional, UF, município e dentro da própria aglomeração).

trecho_rank_nacional_densidade / trecho_rank_uf_densidade / trecho_rank_municipal_densidade

Rankings do trecho por densidade linear.

Geometria (opt-in via incluir_geometria)

geometria

Polígono da aglomeração em **GeoJSON** (padrão) ou **WKT** (com `wkt=true`). SRID 4326, sem simplificação. Requer role `admin` ou `viewer:commercial_cluster`. Não suportado no endpoint `/batch`.

Referência

## Detalhes Técnicos

#### Fontes

  * Base proprietária PrismaData de PDVs (CNPJ ativos com CNAE de varejo/serviço)
  * Malha viária OpenStreetMap para segmentação de trechos
  * Dados sociodemográficos do IBGE para renda mediana e percentis

#### Metodologia

Detecção de concentração comercial por clusterização espacial de PDVs, com classificação em vocação, porte e faixa de renda. Score ponderado combina densidade e volume; rankings recalculados a cada versão.

#### Frequência de Atualização

Base versionada — atualizações incrementais podem ser fixadas via parâmetro `versao_dados`. Sem esse parâmetro, retorna sempre a versão mais recente.

#### Cobertura

Aproximadamente **11 mil aglomerações** mapeadas em todo o território nacional, com maior densidade em regiões metropolitanas. Pontos fora do `raio_km` configurado não retornam aglomeração.

Atenção

## Limitações

####  Considere ao utilizar 

  * O retorno da **geometria** requer role `admin` ou `viewer:commercial_cluster`. Sem essa role, requisições com `incluir_geometria=true` retornam `403 GEOMETRIA_NAO_AUTORIZADA`.
  * O endpoint `/batch` aceita no máximo **1.024 pontos** por chamada e não suporta o retorno de geometria.
  * Pontos fora do `raio_km` (default 5 km, máx. 50 km) não retornam aglomeração — mesmo que exista uma em uma distância maior.
  * O ranking `rank_*_densidade` pode ser dominado por aglomerações pequenas e ultra-densas — combine sempre com `porte` e `qtd_pdvs` para evitar viés.

## Pronto para testar?

Abra o playground interativo de Aglomerações Comerciais e teste com suas próprias coordenadas, filtros e rankings.

[ Abrir Playground  ](<../api-playground/aglomeracoes-comerciais/>)