Custom maps

A custom map is a saved composition: some of your files stacked as layers, styled the way you want, over a basemap you picked. It has its own link, its own embed code, and its own access setting.

This page covers building one in the web app. If you would rather write the map as JSON and create it from the CLI, MCP, or the API, the same map is described field by field in Map documents.

Making one

Go to Custom Maps and choose New map. You get a title, an optional description, category, and tags, then a layer picker.

Add any file that has finished processing. You can add the same file more than once, which is useful when you want to show one dataset two ways, say points coloured by type on one layer and sized by value on another. Each copy is styled on its own.

Layer order

The layers panel lists layers from top to bottom the same way they draw on the map: the first row sits on top. Drag the six-dot handle on the left of a row to restack them. A time series stays one row; expanding its frames does not change the stack. Note that a map document stores the reverse order: spec.layers[0] is the bottom layer, so the first row here is the last entry there. See Map documents.

The eye on a row hides that layer only. Hiding a shapefile or raster next to a time series leaves the series on. The eye on the series row turns the whole series off. Expanding the series and turning off one frame pins that frame without hiding your other layers.

If you delete a file that a map still uses, that layer stays on the map until you take it off. In the builder it is labelled (not in Files). Use Remove on that row, or Remove missing layers under the warning, then save.

The opening view

Whatever a visitor sees first is set here, not wherever you happened to leave the map.

  • Use current view as initial takes the camera position you are looking at right now.
  • Min zoom and max zoom stop people from zooming further out or further in than your data supports. The builder suggests sensible limits from the layers you picked.
  • Pan bounds keep the map inside a box. Draw it on the map or type the coordinates. Worth setting for a city or site map, so visitors do not end up lost in the ocean.
  • Default view for visitors picks 2D or terrain, and flat map or globe. Visitors can still switch once they are in.

Basemaps

Pick a basemap and a theme. Themes are default, dark, forest, ocean, warm, satellite, minimal-light, and minimal-dark.

Labels, roads and rail, and boundaries are separate toggles, so you can put a labelled street basemap under an opaque raster without the labels disappearing, or strip everything back to plain ground under a busy vector layer.

Styling layers

Open a layer's style editor with the pencil in the layers panel. What you get depends on whether the layer is vector or raster.

Vector layers

Three ways to colour a layer:

Simple is one colour for everything. Set fill and stroke separately, each with its own opacity, and a stroke width between 0.5 and 24. This is the right choice more often than people expect.

Categorized colours features by an attribute: land use type, status, owner. Pick the attribute and press Classify. Sarkoa reads the actual values in your file and assigns each one a colour. Up to 50 classes.

You get three palettes. Distinct is the default and tries to keep neighbouring classes easy to tell apart. Colorblind-safe uses the Okabe-Ito set. If two adjacent categories end up looking similar, Shuffle colors reassigns them without changing the classification.

A common mistake is setting the attribute and stopping there. Choosing an attribute does not colour anything until you press Classify, and a map saved in that half-finished state draws as a single flat colour.

Graduated buckets a numeric attribute into ranges and paints them along a colour ramp. Choose the number of classes and how the breaks are calculated:

  • Equal interval cuts the range into equal-width bands. Good when the values are evenly spread.
  • Quantile puts the same number of features in each class. Good when they are not.
  • Natural breaks (Jenks) finds gaps in the data and cuts there.
  • Manual lets you type the breaks yourself.

You can normalize by a second attribute, which is how you get a rate rather than a count. Population divided by area, incidents divided by households, that kind of thing.

Raster layers

What you can adjust follows from how the file was classified during processing, which is covered in File optimization.

  • Visual imagery gets opacity and band selection.
  • Measurement values get a colour ramp with adjustable minimum and maximum, plus the option to hide values outside a range.
  • Categorical maps use the colour table from the source file.

If a raster is offering the wrong controls, it was probably sorted into the wrong kind. Switch it in Processing details on the file.

Legends

Every styled layer can have a legend entry. Set the legend title on the layer, then choose where the legend panel sits and whether visitors can collapse it. You can reorder entries so the layer people care about is at the top.

Legends work for simple styles too, not only categorized and graduated ones.

Popups

Turn on popups for a vector layer and clicking a feature opens its attributes. Choose which field is the heading and which fields are listed underneath. You do not have to show all of them, and usually should not.

If your data has a column of image URLs, list it under image fields and the popup renders thumbnails instead of raw links.

Filters

Filters are map-level controls that appear in a Filters panel for visitors. They are the difference between a map people look at and a map people use.

  • A slider filters a vector layer by a numeric property, or sets the visible value range on a single-band raster.
  • A dropdown filters by a category.
  • A toggle shows and hides layers.

Set the minimum, maximum, step, and where the control starts. Visitors move it and the map responds immediately. Their position is not saved back to the map, so the next person still gets your default.

Attribution

Each layer can carry its own credit, shown in the bottom right when that layer is on. Set the text and an optional link on the layer. Leave it empty to use whatever credit is stored on the file itself, which saves retyping the same source on every map.

Collaboration

Viewers can leave comments (Community and above) or draw on the map together in real time (Essential and above). You can also let them download the source files or add layers of their own. Each is a separate toggle with its own audience, covered in Collaboration.

Publishing

Map access is set on the map. The five modes and what they mean are in Sharing and access.

Before publishing publicly, make sure every layer on the map is also set to public. A private layer will not draw for someone outside your organization, and the map will look like it is missing half its content.

Once the map is public, the Custom Maps page gives you both a link and an embed snippet. Putting it on your own site is covered in Embeds.

Editing safely

Maps carry a revision number. If two people have the same map open and both save, the second save is rejected rather than silently overwriting the first. Reload and reapply your change.

The CLI and MCP expose this as --expected-revision and expected_revision. In the app it is automatic.