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

{
  "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

{
  "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).

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

Documentação > Aglomerações Comerciais