DATTA BI — Visuais de mapa (OpenStreetMap e Google Maps)

Dados com latitude e longitude merecem mais do que uma tabela. O DATTA BI traz dois visuais de mapa prontos na galeria — Mapa OSM e Google Maps — para plotar atendimentos, ocorrências ou unidades no território com um arrasto, e ainda filtrar o resto do dashboard clicando num marcador.

A seção "APIs do Google Cloud exigidas pela chave" vale para toda a plataforma, não só para o DATTA BI: a mesma GOOGLE_MAPS_API_KEY atende também o mapa do Chat e a página Investigar.

Qual dos dois usar

Cenário	Visual	Por quê
Instalação sem internet ou sem chave do Google	Mapa OSM	Não exige chave de API nenhuma
Quer começar rápido, sem depender do administrador	Mapa OSM	Arraste e pronto
Precisa da base cartográfica e do detalhamento do Google	Google Maps	Depende de chave configurada na instalação

Mapa OSM (`type: 'map'`)

Sem chave de API. Os tiles vêm de tile.openstreetmap.org via maplibre-gl.
Boa escolha para instalação local (Diretrizes do Projeto §6): funciona em ambiente totalmente isolado da internet, desde que você espelhe os tiles internamente.

Google Maps (`type: 'map-google'`)

Requer a GOOGLE_MAPS_API_KEY configurada pelo administrador na instalação, por uma de duas vias:
- o valor googleMaps.apiKey da configuração de instalação (sobrescrevível na linha de comando ou por segredo), ou
- o segredo dedicado datta-google-maps-secret, na chave GOOGLE_MAPS_API_KEY.
A interface obtém a chave em tempo de execução por um endpoint de configuração da plataforma — veja a referência de API.
Sem chave configurada, nada quebra: o card cai em um placeholder.

APIs do Google Cloud exigidas pela chave

A GOOGLE_MAPS_API_KEY é única e compartilhada por toda a plataforma — o mesmo endpoint de configuração serve o DATTA BI, a página Investigar e o mapa do Chat. Cada consumidor exige APIs diferentes habilitadas no projeto Google Cloud da chave:

Consumidor	Recurso usado	API que precisa estar habilitada
DATTA BI (visual `map-google`)	tiles do mapa	Maps JavaScript API
Chat — modal Localização	`Geocoder`, Street View	Maps JavaScript API, Geocoding API
Investigar — mapa do CEP	`Geocoder`	Maps JavaScript API, Geocoding API
Investigar — busca de serviços próximos	`Place.searchNearby` / `Place.searchByText`	Places API (New)
Investigar — distâncias e rotas	matriz de distâncias, cálculo de rotas	Distance Matrix API, Directions API

A "Places API (New)" é obrigatória para a busca de serviços próximos. Até 2026-07 a página Investigar usava a busca de proximidade da Places API legada — que o Google deixou de liberar para chaves novas em 01/03/2025 e que não pode mais ser habilitada em projetos Google Cloud novos. Chaves criadas depois dessa data recebiam REQUEST_DENIED em toda busca. A página foi migrada para Place.searchNearby (categorias por tipo: escola, hospital, farmácia, delegacia) e Place.searchByText (categorias por termo: CRAS, CREAS, UPA, CAPS, defensoria) — a Nearby Search nova não aceita texto livre, e por isso as duas chamadas coexistem.

Sintoma de API faltando: a lista de serviços próximos volta vazia. Desde a migração, a tela mostra a mensagem apontando para a "Places API (New)" em vez de ficar em silêncio; o motivo exato de cada categoria vai para o console do navegador.

Proteja a chave

A chave é exposta ao navegador — é uma chave de frontend. No console do Google Cloud, restrinja-a por HTTP referrer aos endereços da sua instalação DATTA e limite a lista de APIs habilitadas às da tabela acima. Nunca deixe a chave irrestrita.

O que o visual espera receber

json

{
  "lat": { "column": "latitude" },
  "lng": { "column": "longitude" },
  "label": { "column": "cidade" },
  "value": { "column": "atendimentos" }
}

lat / lng: numéricos, obrigatórios.
label: opcional, exibido no balão do marcador.
value: opcional, controla o tamanho do marcador.

A tradução desses bindings gera o DATTAX que alimenta o mapa:

EVALUATE FROM GRAPH "..." MATCH "..."
  |> SELECT lat, lng, cidade AS label, atendimentos AS value
  |> LIMIT 1000
  |> TABLE;

Passo a passo — mapa de atendimentos por cidade

Prepare um dataset com as colunas latitude, longitude, cidade e atendimentos.
No modo de edição do dashboard, arraste o visual Mapa OSM para o canvas.
Ligue as colunas aos canais: latitude, longitude, rótulo (cidade) e valor (atendimentos) — os marcadores aparecem dimensionados pelo volume.
Clique no marcador de uma cidade: os outros visuais do dashboard filtram na hora para aquela cidade.

Filtro cruzado no mapa

Clicar num marcador emite o filtro cruzado pelo label do ponto — ou pelas coordenadas lat/lng, quando não há rótulo. Os demais visuais do dashboard re-renderizam já filtrados, exatamente como no filtro cruzado de qualquer outro visual.

Desempenho

O visual plota até 1.000 marcadores por padrão. Acima disso, agrupe: por clusterização no cliente (especificação de cluster do maplibre) ou por grade geográfica H3 no backend.
Para bases massivas, materialize uma visão agregada por grade geográfica com o Trino e aponte o mapa para ela, em vez de renderizar ponto a ponto.

Detalhes técnicos

Os dois visuais são renderizados pelo mesmo componente, variando apenas o provider:

window.DattabiMapD3.create(container, { provider: 'osm', /* ... */ });
window.DattabiMapD3.create(container, { provider: 'google', /* ... */ });