Map points
A point map places one mark per row at a latitude and longitude. The atlas is the land behind the marks. encoding.size turns the marks into bubbles.
When to use it
Use a point map when each row is a place you can point to, not a region you shade. Largest urban areas is one bubble per city, sized by population.
A choropleth shades regions from a name or an id. It has no latitude column. Use it when the value belongs to the whole area.
A scatter also draws a point per row, and both axes are quantities. A point map does not. Longitude and latitude are a location, not encoding.x and encoding.y. A heatmap colors a grid of cells. It does not place cities on land.
Data
One row per point. encoding.latitude and encoding.longitude name the columns. lat and lon are aliases. A latitude outside −90 to 90, or a longitude outside −180 to 180, is skipped.
encoding.label is the name drawn next to a point. encoding.size is the bubble field. encoding.color can be a second number. When color and size are the same field, the bubbles stay one accent and the legend is a size key. Largest urban areas does that with pop.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest point map. version, type, and a11y.alt are required. Tokyo and Sydney, labeled, with no size channel, so both marks share one radius. The atlas is the world. There is no tile layer, and no pan or zoom.
{
"version": "1",
"type": "map-points",
"data": [
{
"name": "Tokyo",
"lat": 35.7,
"lon": 139.7
},
{
"name": "Sydney",
"lat": -33.9,
"lon": 151.2
}
],
"encoding": {
"latitude": "lat",
"longitude": "lon",
"label": "name"
},
"mark": {
"atlas": "world"
},
"a11y": {
"alt": "Tokyo and Sydney are marked on a world map."
}
}Install @chartkitdev/geo. Maps are not in @chartkitdev/core, and the framework adapters do not draw them. render from the geo package is async. spec is the JSON above.
import { render, validate } from "@chartkitdev/geo";
const checked = validate(spec);
const svg = await render(spec);render from @chartkitdev/core does not draw this type. Core validate() warns CK3057 and leaves latitude and longitude to the geo package. Call validate from @chartkitdev/geo. Its warnings are CK3050 through CK3056, and the SVG still draws.
Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.
Examples
The rail shows Largest urban areas, the cities map already published for this type. Twenty-two cities. Size and color are both population. mark.labelCount is 18. The title is the example name. There is no counter and no previous or next control, because this page has one example.
Atlas
mark.atlas is world, us, canada, or eu. Omit it and the map is the world. The US atlas pairs with mark.projection albersUsa. World, Canada, and the EU pair with equalEarth. This control writes that pair. Largest urban areas is the world.
{
"mark": { "atlas": "world", "projection": "equalEarth" }
}The points have to fall on the atlas you pick. These rows are world cities. Another atlas clips marks that land outside its frame. mercator, equirectangular, and fit stay in the playground.
Size
encoding.size is the bubble channel. It is a field name, or an object with field, format, and title. Omit it and every point uses one radius. Largest urban areas sizes by pop.
{
"encoding": {
"size": { "field": "pop", "format": { "suffix": " million" }, "title": "Population" }
}
}Off removes the channel. On puts this example's size channel back, including its format and title. Largest urban areas also sets encoding.color to pop. While size and color are the same field, the bubbles stay one accent. Remove size and that color field paints a ramp, and the radius is shared.
A pixel range on the size channel is not what sets these radii. The geo renderer maps the field from the smallest value to the largest. Set a separate color field, or encoding.color.scale.type, in the playground.
Labels
encoding.label is the name of each point. Omit it and the marks stay, without tags. mark.labelCount is how many of the largest points try to take a tag. Omit it and the cap is 12. Largest urban areas sets 18.
{
"encoding": { "label": "name" },
"mark": { "labelCount": 18 }
}Off removes encoding.label. On puts the example's label field back. labelCount stays on mark. Change the cap in the playground.
Legend
A size legend is on when the bubbles encode a field. A color legend is on when color is its own number. Omit legend and it sits on the right. legend.position "bottom" moves it under the map. "right" is the other side this chart draws. top, left, and inside are not drawn.
{
"legend": { "position": "bottom" }
}{
"mark": { "legend": false }
}Off writes mark.legend: false. That is the key that hides the legend. legend: false does not. The map still draws the legend on the right.
Tooltip
On the other charts, omit tooltip and the hover card is on. tooltip: false turns that card off. tooltip: true turns it on. This control writes the same keys, so a spec you carry to those charts behaves the same way.
{
"tooltip": false
}{
"tooltip": true
}@chartkitdev/geo does not read tooltip: false yet. The point title stays in the SVG, and attach() from that package still shows it. Off updates the snippet. It does not remove the title. Turning the control back on deletes an omitted tooltip, or puts a tooltip object back if the example had one. Largest urban areas does not set tooltip.fields. Add extra hover columns in the playground, with tooltip.fields or encoding.tooltip.
The rest of the spec
mark.land and mark.water take a #rrggbb color. A point map does not hatch empty regions. Theme presets live on the playground. This page does not add a theme control. The example keeps the size written on the spec.