map (UF), mapcity, bubblemap, geoheat

Selo de estado: Preview (teto atual do produto) · Curso ACD-330 — Dashboards: visuais, filtros, interações e design · Aula 6 de 12 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai plotar receita por UF e município.

Vídeo#

Identificador: acd-330-06-mapas-do-brasil · Duração-alvo: 6 min · Tela: /dashboards.

Roteiro (capítulos):

1. 0:00–1:15 — map (UF) (/dashboards/[id]) — categoria de dado UF e o preenchimento coroplético.
2. 1:15–2:30 — mapcity (/dashboards/[id]) — a malha municipal carregada sob demanda.
3. 2:30–3:45 — bubblemap (/dashboards/[id]) — pontos exatos por latitude/longitude.
4. 3:45–4:45 — geoheat (/dashboards/[id]) — densidade quando há muitos pontos.
5. 4:45–6:00 — por que isso é Preview — rede, cache e o que fica fora da conta.

Conteúdo#

Quatro visuais para "onde isso acontece no Brasil"

A família de mapas é o diferencial do catálogo frente a ferramentas que tratam mapa como visual pago ou extra: cinco visuais nativos, dos quais quatro entram nesta aula. map pinta o Brasil por UF (27 estados); mapcity detalha por município, carregando a malha do estado sob demanda; bubblemap posiciona pontos exatos por latitude/longitude, com o tamanho da bolha pela métrica; geoheat mostra densidade a partir de pontos lat/long, útil quando há tantos pontos que bolhas individuais se sobrepõem. O quinto visual da família, maplayers (mapa com camadas geográficas), fica fora do recorte prático desta aula — vale explorá-lo pela aba Inserir depois de dominar os quatro básicos.

Como aparece no produto

Para o map funcionar, uma coluna do modelo precisa estar marcada como categoria de dado UF (ver Modelo semântico) — sem essa marcação, o visual não sabe ligar "SP"/"São Paulo" a um estado no mapa. O mapcity exige o mesmo tipo de marcação para município, mas com uma diferença de arquitetura: a malha geográfica do estado é buscada sob demanda por uma rota interna (/api/geo/br/[uf]) com cache de 30 dias — abrir um mapa de um estado que ninguém olhou ainda busca a malha pela primeira vez; os próximos acessos vêm do cache.

bubblemap e geoheat não dependem de categoria de dado — eles leem colunas de latitude/longitude diretamente, normalmente de um cadastro de filiais ou clientes com coordenadas gravadas. A escolha entre os dois depende da densidade: poucos pontos (filiais, por exemplo) leem melhor como bolhas individuais; muitos pontos (pedidos de um dia inteiro numa região metropolitana) leem melhor como mapa de calor.

Exemplo na Aurora Varejo

Marque filiais.uf como categoria UF no modelo e monte um map de Receita por estado: SP=250, RJ=90, MG=140 — o preenchimento mostra de cara que SP concentra a receita. Para o detalhe dentro de SP, abra mapcity e confira o carregamento da malha municipal (a primeira abertura busca pela rede; reabrir é imediato pelo cache). Se a Aurora cadastrar lat/long das filiais, um bubblemap dimensiona cada ponto pela receita — útil numa reunião para "mostrar onde estamos", mesmo sem pensar em UF/município.

Erros comuns de design

• Esquecer a categoria de dado. Sem marcar a coluna como UF/município no modelo, map/mapcity não pintam nada — o erro mais comum ao configurar mapa por aqui.
• Mapa por município para visão nacional. Com todas as 27 UFs envolvidas, abrir município a município é lento e ilegível — comece pelo map (UF) e só desça ao mapcity dentro de um estado específico.
• Bubblemap com centenas de pontos. Bolhas se sobrepõem e o visual vira uma mancha — nesse volume, geoheat (densidade) comunica melhor do que pontos individuais.
• Confiar na malha sem rede. Como a malha municipal depende de busca externa e cache quente, um ambiente sem rede ou com cache frio pode demorar a preencher — nunca trate isso como instantâneo numa demonstração ao vivo sem testar antes.
• Cor sem escala visível. Num mapa coroplético, sem legenda de intensidade o leitor não sabe se o verde é "bom" ou "muito bom" — mantenha a escala de cor visível.

Estado atual (Preview)

Os quatro mapas estão em Preview, e não por acaso — é a única família desta aula com esse selo (as demais aulas herdam Preview do editor; esta família carrega Preview por si mesma): a geometria da malha (UF e município) é testada e determinística, mas a latência de carregamento da malha municipal em produção é NÃO MEDIDO (depende de rede externa IBGE e cache quente). Marcar como Preview aqui é mais conservador do que o resto do catálogo — e intencional.

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /dashboards no console):

1. No modelo, confirme que filiais.uf está marcada como categoria de dado UF.
2. Na página "Resumo" do painel "Comercial — Aurora", insira um map de Receita por filiais.uf.
3. Abra um mapcity do estado de SP e observe o carregamento da malha municipal.
4. Insira um bubblemap com as filiais da Aurora, dimensionado pela receita.
5. Insira um geoheat dos mesmos pontos e compare a leitura com o bubblemap do passo 4.
6. Verifique se a escala de cor do map tem legenda de intensidade visível.
7. Reabra o mapcity do passo 3 e confirme que a segunda abertura é mais rápida (cache).

Você terminou quando: a página tem os 4 mapas desta aula, com filiais.uf corretamente marcada e a escala de cor do map visível.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• bi/visuais/map
• bi/visuais/mapcity
• bi/visuais/bubblemap
• bi/visuais/geoheat

Capacidades ensinadas#

(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".