Analyze places with the map canvas

Lesson 3 of 410 min

What you'll learn

you can get a map by asking a spatial question in chat, and explain why there's no map button
you can open a map full screen with "View large", switch basemaps, and read the legend
you can select a feature, hand it to the agent as an @mention, and jump from a pin to the knowledge graph
you can ask follow-up spatial questions like nearest, within-radius, real routes and travel times, once places are remembered in the graph

Use a map to inspect distances and patterns in location-based material, such as customer meetings, incident addresses, or travel plans.

Ask "put my client meetings on a map" or "what's within 15 minutes of the office?" in chat. The agent geocodes the places, runs the analysis, and displays a map you can pan, zoom, and select.

The map canvas with authored places, analysis layers, and pin details.

Request a map in chat

There's no map button or sidebar icon anywhere in the app. A map only exists once the agent calls its write_map tool during a chat turn. So to get one, ask for a map in any chat.

While the place names turn into coordinates you'll see a "Geocoding places" card. Then an "Authored map" card appears, with the live map inline right below it. Pan, zoom, and click all work on the spot.

How the agent builds a map

The agent writes out a declarative JSON "mapspec": a title, an opening camera view, a basemap choice, and layers bound to GeoJSON data. The app validates that spec twice, once when it's written and again right before it renders, then compiles it to native map layers.

The model never writes rendering code and never makes up geometry. Every coordinate comes from real geocoding, so everything you see on the map traces back to an actual place.

A map is built from 8 layer types, and you can stack and combine them however you like:

scatterplot: dots for your pins and bubbles (radius can encode a numeric value)
heatmap: a soft density glow
geojson: polygons and lines, like district boundaries or choropleths (regions shaded by a value)
path: routes
text: labels placed on the map
hexagon: automatic hex-binned density, with a real value per cell
arc: great-circle links between origin and destination pairs
raster: a tile-imagery overlay, such as live weather

Open it big

The inline card's footer has a "View large" button. Click it and the map opens as a full-screen tab (map-pin icon, titled with the map's name). The chat tucks into the left sidebar, so you keep talking while you look.

The usual gestures work: drag to pan, scroll or pinch to zoom, right-drag to rotate and tilt. On open, the camera auto-fits all the data, and maps with 3D extrusions open already tilted.

Control	Where	What it does
Navigation control	Top-right	Zoom in, zoom out, and a compass/pitch button that resets north and flattens the tilt
"Map style" button	Top-right, below navigation	Basemap menu: "Standard" (default 3D), "Faded", "Mono", "Light 2D", "Dark 2D", "Satellite". Your pick sticks even when the agent re-authors the map
Legend	Bottom-right, full screen only	A color swatch and label for every category, choropleth range (like "≥ 50"), or layer
Time scrubber	Bottom-center, when the map has a time dimension	Replays time-stamped data (more on this below)
Hover tooltip	Any interactive mark	A small popup listing the feature's fields (heatmap layers are the exception: not hoverable or clickable)

The inline map is clean by design

In the transcript, the map renders with no title or legend overlay. The agent explains what the colors mean right there in its reply, so the picture stays clean.

Want the full legend? Open it big: the full-screen tab lays out every category and range.

Select a place on the map and ask about it

Map to chat to graph

Click a mark
A pill appears at the top of the map: "Selected: {label}", with an "×" button ("Clear selection") to undo it. Clicking an empty part of the map clears it too.
The composer picks it up
An @label mention chip drops into the chat composer. Your next message quietly carries the feature's full properties and coordinates, so "why is this one an outlier?" just works.
Ask about exactly that place
Send the message. The agent gets the exact feature you clicked, with all its data. You never have to describe which dot you meant.
Jump to the knowledge graph
If the feature you clicked is tied to one of your entities, the pill also shows a "View in graph" button. One click opens the graph view focused on that entity.

Analyze distance, routes, and distribution

The map does real work. The app computes spatial analytics itself, deterministically, and real-world travel geometry comes from live services instead of straight-line guesses.

You ask	What runs
"Where do incidents cluster?"	Hex-binned density, or a `hotspot` analysis (Getis-Ord Gi*) that finds statistically significant hot and cold spots
"Where is it spreading?"	`emergingHotspot`: a space-time trend test that labels each cell as intensifying, diminishing, persistent, new, sporadic, or historical
"How do I get from A to B?"	`directions`: actual road, walking, or cycling routes between your waypoints, with distance and duration
"What's within 15 minutes of the office?"	`isochrone`: real travel-time reach polygons showing everywhere you can get to within N minutes, in several nested time bands at once
"Which warehouse is fastest to reach from each store?"	`travel_matrix`: an origin-to-destination travel-time matrix across your points
"What's within 2 km of the warehouse?" (no map open)	`query_geo`: nearest, within-radius, bounding-box, or inside-a-polygon queries over places your graph already remembers

GeoSPARQL: how a graph remembers a place

GeoSPARQL is the open W3C/OGC standard for geography in a knowledge graph. A location is just another fact, stored as a coordinate literal like "POINT(lon lat)" on the entity.

When the agent maps a point tagged with one of your entities, that coordinate goes into a dedicated derived graph, kept separate from your notes' own facts. Machine-derived coordinates never mix with what your notes actually said, and they survive a note re-extraction.

What the graph remembers about a place

(Kyoto Station)  -located at->  POINT(135.7587 34.9858)

This is the map's lasting payoff. Once a place has been on a map with an entity binding, the agent can answer spatial questions about it without drawing anything at all. Ask for "the 5 nearest customers" or "every asset inside this district", and query_geo handles it in any future conversation.

Inspect map data by time

If the mapspec declares a time field, the map grows a time scrubber: in the inline card's footer, or bottom-center in the full-screen tab (accessible name "Time scrubber"). It starts at the end, with everything visible.

Drag it left and features filter cumulatively up to the moment you pick. Because the transforms recompute on the filtered data, hexbins, hotspots, and choropleths all animate as you drag. Scrubbing never re-frames the camera, so you can watch one neighborhood while the pattern replays.

Get your first map

Open a chat and ask something spatial: "Put the places mentioned in my notes on a map."
Watch the transcript: a "Geocoding places" card resolves the names, then an "Authored map" card appears with the live map beneath it.
Click "View large" in the map's footer to open it as a full-screen tab.
Open the "Map style" menu, switch to "Satellite", then go back to "Mono", and notice the legend in the bottom-right.
Click a mark, read the "Selected" pill, and send a follow-up: "tell me more about this one."

The map opens full screen with the chat paired on the left. Your clicked feature rides along as an @mention, and the agent answers about exactly that place. If the mark is one of your entities, the pill also carries a "View in graph" button.

mapspec: The declarative JSON the agent writes: title, camera, basemap, layers. Validated twice, then compiled to native map layers.
transform: A parametric spatial computation the app runs on a layer's data: hexbin, kernel density, buffers, clusters, voronoi, hotspot statistics, and more.
geocoding: Turning place names into coordinates through OpenStreetMap, forward or reverse, one name or a whole batch at once. Every coordinate is a real, resolved location.
isochrone: A travel-time reach polygon: everywhere you can get to within N minutes, computed on the real road network.
time scrubber: The slider on time-aware maps that filters features cumulatively up to an instant, recomputing analytic layers live as you drag.
query_geo: The agent tool that answers nearest, within-radius, and in-polygon questions over entity coordinates the knowledge graph has remembered.

Ask for a coverage ring when you mean distance

Dot size is a screen-pixel channel. It's good for showing magnitude, but it says nothing about distance on the ground.

When you want a real geographic radius, like everything within 2 km of a warehouse or a 10-minute walk around each clinic, ask for exactly that. The agent draws a true buffer polygon, or a travel-time isochrone, sized by real distance.

A map is a canvas the agent authors inside your conversation. The design canvas takes that same move to screens: the agent draws one, and you grab it and tweak it.

← Previous lesson