mapbench

Documentation → Tutorials

Your first map

One pass through the whole product: a file goes in, a published map comes out. Twenty minutes, most of it spent waiting for tiles to build. Bring any spatial file you already have.

Before you start

  • A mapbench account, and a project to work in. Accounts are created by invitation — request access if you do not have one.
  • A vector spatial file: GeoJSON, GeoPackage, FlatGeobuf, a zipped Shapefile, KML/KMZ, CSV with coordinates, GML or GPX. Anything up to 1 GiB. Formats and limits has the exact list.
  • If you have nothing to hand, most national and state agencies publish administrative boundaries as GeoJSON. Something small — a few thousand features — makes the first pass quick.

Step 1. Add a dataset

  1. Sign in and choose Datasets in the sidebar.
  2. Choose New, then From file.
  3. Give it a Name — what you want to see in the catalogue, e.g. Parks.
  4. Set the Layer name. This is the name baked into the tiles themselves, so it is lower-case with underscores, e.g. parks. It cannot be changed later — see the note below.
  5. Drop the file onto the upload area, or click to browse.
  6. Choose Upload & Queue.

The layer name is permanent. Every published map and embed refers to it, so mapbench will not rename it afterwards — the display Name is the one you can change freely. If you get it wrong, the fix is a new dataset. Picking a short, plain name now is worth the ten seconds.

Shapefiles are the one format that is more than one file. Zip the .shp, .shx, .dbf and .prj together and upload the .zip; uploading the .shp alone produces a dataset with no attributes and no coordinate system.

Step 2. Wait for it to tile

Uploading is not the slow part — building the tiles is. The dataset appears in the catalogue straight away and moves through a few states:

StateWhat is happening
PendingQueued. A worker has not picked it up yet.
ProcessingFetching, converting to a common format, tiling, then uploading the tiles.
ReadyTiles exist. The dataset can go on a map.
ErrorSomething failed. The job carries the message and the log.

Open the processing panel from the Datasets page to watch progress, read a failed job's log, cancel something still queued, or queue a Reprocess. A few thousand features finish in seconds; a few million take minutes.

If it fails, the message is usually one of three things: an unreadable or incomplete Shapefile bundle, a file with no geometry column mapbench could find, or a source with no coordinate reference system declared. Fix the file and upload it again.

Step 3. Look at what you got

Select the dataset in the catalogue. Two things are worth checking before you build anything on top of it:

  • The preview rows — the real attribute table. This is the authoritative answer to "what are the fields actually called".
  • The field statistics — per-field types, ranges and common values. These are what the style editor offers you when you colour by a field, so a field that is missing here cannot be styled by.

While you are here, fill in the description, the licence and the attribution under Edit dataset. mapbench never blocks you for leaving them empty, but attribution is a licence obligation for a lot of open data, and the share page can only publish a credit you have recorded.

Step 4. Style it

Styling belongs to the dataset, so every map that uses it starts from the same look. Set fill and stroke colours, opacity, width and point size — and, where it is useful, drive one of those from a field so the colour carries meaning rather than just distinguishing layers.

A style set on the dataset is the default; a map may override it for its own copy of the layer, and Reset to the dataset's style in the map editor puts it back.

Step 5. Build the map

  1. Choose Maps in the sidebar, then New map.
  2. Pick a basemap.
  3. From the dataset picker, Add to map for the dataset you just made. Add as many as you want — they stack.
  4. In the layer panel, drag to reorder (the top of the list draws on top), toggle visibility, zoom to a layer, or override its style for this map.
  5. Set the map's name and description, and save the view — the centre and zoom you leave it at is what a visitor opens on.

The description is not decoration. A published map is the entire page someone sees, so if your fill colour encodes four categories, this is the only place you can say so.

Step 6. Publish it

  1. Choose Share map.
  2. Choose Create share link.
  3. Copy the share link — a full-page map with a title and a preview card — or the embed code for another site.

A share link is public. Anyone holding the URL can view every layer in that map, without signing in. There is no password on it. Revoke it from the same dialog and access ends immediately.

Publish and share a map covers embedding, rotating a link and what a viewer can and cannot do with it.

Where to go next