DATTA BI — Map visuals (OpenStreetMap and Google Maps)

Data with latitude and longitude deserves more than a table. DATTA BI ships two ready-made map visuals in the gallery — Mapa OSM and Google Maps — so you can plot service records, incidents or facilities on the territory with a single drag, and still filter the rest of the dashboard by clicking a marker.

The "Google Cloud APIs required by the key" section applies to the whole platform, not just DATTA BI: the same GOOGLE_MAPS_API_KEY also serves the Chat map and the Investigar page.

Which of the two to use

Mapa OSM (type: 'map')

• No API key. Tiles come from tile.openstreetmap.org via maplibre-gl.
• A good choice for a local installation (Project Guidelines §6): it works in an environment fully isolated from the internet, as long as you mirror the tiles internally.

Google Maps (type: 'map-google')

• Requires the GOOGLE_MAPS_API_KEY configured by the administrator at installation, through one of two paths:
  • the googleMaps.apiKey value in the installation configuration (overridable on the command line or by a secret), or
  • the dedicated datta-google-maps-secret secret, under the GOOGLE_MAPS_API_KEY key.
• The interface fetches the key at runtime through a platform configuration endpoint — see the API reference.
• With no key configured, nothing breaks: the card falls back to a placeholder.

Google Cloud APIs required by the key

The GOOGLE_MAPS_API_KEY is a single key shared across the whole platform — the same configuration endpoint serves DATTA BI, the Investigar page and the Chat map. Each consumer requires different APIs enabled in the key's Google Cloud project:

The "Places API (New)" is mandatory for the nearby services search. Until 2026-07 the Investigar page used the legacy Places API's proximity search — which Google stopped granting to new keys on 2025-03-01 and which can no longer be enabled in new Google Cloud projects. Keys created after that date received REQUEST_DENIED on every search. The page was migrated to Place.searchNearby (categories by type: school, hospital, pharmacy, police station) and Place.searchByText (categories by term: CRAS, CREAS, UPA, CAPS, public defender's office) — the new Nearby Search does not accept free text, which is why both calls coexist.

Symptom of a missing API: the nearby services list comes back empty. Since the migration, the screen shows a message pointing at the "Places API (New)" instead of staying silent; the exact reason for each category goes to the browser console.

Protect the key

The key is exposed to the browser — it is a frontend key. In the Google Cloud console, restrict it by HTTP referrer to your DATTA installation's addresses and limit the list of enabled APIs to the ones in the table above. Never leave the key unrestricted.

What the visual expects to receive

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

• lat / lng: numeric, required.
• label: optional, shown in the marker's popup.
• value: optional, controls the marker size.

Translating those bindings produces the DATTAX that feeds the map:

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

Step by step — service records per city on a map

1. Prepare a dataset with the latitude, longitude, cidade and atendimentos columns.
2. In the dashboard's edit mode, drag the Mapa OSM visual onto the canvas.
3. Bind the columns to the channels: latitude, longitude, label (cidade) and value (atendimentos) — the markers show up sized by volume.
4. Click a city's marker: the dashboard's other visuals filter to that city right away.

Cross-filter on the map

Clicking a marker emits the cross-filter by the point's label — or by the lat/lng coordinates when there is no label. The dashboard's other visuals re-render already filtered, exactly like the cross-filter of any other visual.

Performance

• The visual plots up to 1,000 markers by default. Beyond that, group them: by clustering on the client (the maplibre cluster spec) or by an H3 geographic grid on the backend.
• For massive datasets, materialize an aggregated view by geographic grid with Trino and point the map at it, instead of rendering point by point.

Technical details

Both visuals are rendered by the same component, varying only the provider:

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