The Mapji manual

Quick start

From nothing to a published map is about five minutes, most of it spent choosing how the data should look.

1. 1

   Sign in

   Use a GitHub, Google or Microsoft account. The dashboard lives at app.mapji.com.

2. 2

   Create a map

   The create dialog asks for a map type first. Nine types are filled with your own data; Crowdsourced Map is listed separately because its data comes from visitors. Then name the map — the web address is slugified from the name as you type, and you can override it.

3. 3

   Bring your data in

   Upload a file, connect a Google Sheet, or build the map by hand on the canvas. See Importing files for what each type expects.

4. 4

   Configure the type

   The Settings tab in the editor sidebar holds the settings specific to your map type: the heat gradient, the cluster bands, the time column, the store fields.

5. 5

   Style it and set the behaviour

   The buttons on the map itself cover the basemap, what visitors are allowed to do with the map, and which widgets appear. Lock an opening view from the status bar under the map if you want it to always start in one place.

6. 6

   Share it

   The map is already live at yourmap.mapji.com. Point a custom domain at it, or copy the embed snippet to put it inside an existing page.

Accounts & sign-in

Accounts are created by signing in — there is no separate registration step and no password to manage. Three providers are supported: GitHub, Google and Microsoft Entra ID (work or school accounts).

Which one you choose matters in exactly one place. Google Sheets live sync reads the sheet as you, so it needs a Google connection — signing in with Google grants Mapji read-only access to spreadsheets and an offline token so the background sync can keep running when you are not at the keyboard. Signed in with GitHub or Microsoft, every other feature works normally; only Sheets sync is unavailable.

Editor layout

Every map type uses the same editor shell, so the same things are always in the same place. Only the contents change.

Status bar

The strip under an editable map is a readout of the current camera. It updates as you pan and zoom.

Opening view

By default a map opens fitted to its data — whatever you have imported decides the starting camera. That is usually right, and occasionally exactly wrong: a national dataset with one outlier opens zoomed out to nothing, and a map built to show one neighbourhood should not re-frame itself every time the data changes.

Locking the opening view pins the camera. Press the lock in the status bar and the map captures where you are standing right now — centre, zoom, bearing and pitch. From then on the editor, the public map and the embed all open exactly there.

Fine-tune the numbers under Opening view in the Settings tab, where each has an input and a slider, and bearing and pitch share a dial preview. On a Crowdsourced Map the same settings live in the Display tab.

Story Map is the exception and has no lock. Its chapters own the camera, so a fixed opening view would be overwritten by the first scroll. It still shows the readouts.

Choosing a type

Ten types, each built around a different question about your data. The fastest way to choose is to ask what the reader should take away: individual places, density, regional comparison, reachability, change over time, or a narrative.

You can change type later from Settings → General, and your imported features are kept. What does not carry across is the type-specific configuration, because it describes a different rendering: a heat gradient means nothing to a store locator. Draw is the one to be careful with — its features are stored where a Cluster or Heatmap import writes, so switching a Draw map to one of those and then importing replaces the drawing.

Draw

A blank canvas for maps you build by hand: markers on the places that matter, a shaded catchment area, a traced boundary, a route between stops. It is the right choice when the map is the data rather than a rendering of a table.

Tools

Click any feature to open its properties: a name, a description that becomes the popup body, and a colour. Lines show their measured length. Icon markers can have their icon and size changed after the fact from the same panel.

Routes

A route is drawn along the real road network, not as a straight line between points. Build the stop list in a dialog — search an address or switch to picking on the map, insert a stop between two existing ones, reorder by deleting and re-adding.

The route's distance and duration are stored on the line, and its length shows in the feature list alongside every other line you have drawn.

Cluster

Thousands of overlapping pins tell you nothing. A cluster map groups nearby points into a single numbered circle that splits apart as you zoom in, so the shape of the dataset is readable at every scale. Click a cluster to zoom to its contents.

It expects points. Lines and polygons are reduced to a representative point when the map is drawn, so a mixed file still renders — but if your data is mostly areas, a choropleth will say more.

Donut clusters

Pick a property to categorise by, then define the categories. Each is matched either by exact values (one or more values from that column) or by a numeric range. Anything that matches nothing is drawn in a separate uncategorised colour, which is also a quick way to spot dirty data. The result is a cluster that shows composition, not just count — how many of these incidents were severe, how many of these stores are franchises.

Heatmap

A heatmap answers “where is this concentrated?” It blurs individual points into a continuous density surface, which makes patterns obvious and individual records unreadable — that is the trade, and it is the reason a heatmap is a poor choice for data someone needs to look things up in.

Points contribute equally by default. Set a weight column and each point contributes in proportion to that number instead, which is what you want for sales figures or population, and what you do not want for raw events where every record already counts once.

Choropleth

Regions shaded by a value: unemployment by county, turnout by constituency, revenue by country. You do not need boundary files — Mapji ships the geometry and you supply the numbers.

Picking the areas

The area picker is a single search box over a catalog of basemaps. Start with the whole world or a continent, or search for a country and pick the level you want inside it. Choose an entry and you land on a checkbox grid of its regions, so you can take all of them or just a subset.

Areas appear immediately, grey until they have data, and you can come back and add more at any time without disturbing the values already entered.

Attaching values

Upload a CSV or Excel file with a region column and a value column, connect a Google Sheet to keep the values live, or type them straight into the table in the sidebar. The join tries the region name first, then the official code (ISO 3166-2 or the NUTS code), then the country, then an internal identifier, then a partial name match — so “Bavaria”, “Bayern” and DE-BY all find the same region. Anything that fails to match is listed before you commit, so a typo is visible rather than silently absent.

Isochrone

An isochrone shades everywhere you can reach from a point within a given time or distance, following the real network rather than drawing a circle. “Fifteen minutes’ walk” is a far more useful catchment than “one kilometre”, and the two look nothing alike once rivers and motorways are involved.

Place origins by clicking the map, or import a point file to seed them (the first five are used). Bands are drawn as nested translucent polygons, colour-coded from nearest to furthest, over any basemap.

Store Locator

A searchable directory with a map attached: a scrollable list of locations beside the map, filters down the side, and a detail panel for each one. This is the type to reach for when the visitor has a task — find the nearest branch, find one that is open now, find one that does the thing they need.

Search and filters

Free-text search covers every field on every location, so a visitor can type a city, a postcode already in your data, a manager's name or a service. On top of that you define faceted filters from your own columns:

• Select — one choice from a dropdown.
• Multi-select — several choices at once, and a comma-separated cell counts as belonging to each of its values, which is what makes a “services offered” column work properly.
• Range — a numeric slider.

Any one filter can also drive the map: nominate it and each of its options gets its own marker icon, so branches, kiosks and warehouses are distinguishable at a glance without opening anything.

Cards and detail

Time Slider

A timeline under the map that steps through your data one period at a time, with play, pause and scrub. Use it when when is as much of the story as where — an outbreak spreading, a chain opening branches, a fleet moving through a day.

It needs one column holding the time. Mapji tries to detect it on import; confirm or change it in Settings, along with how the values should be read.

Story Map

Long-form writing beside a map that moves as the reader scrolls. Each chapter has its own text and its own camera; crossing into a chapter flies the map to that place. It is the format for a journey, an investigation, a field report, a guided tour.

Write chapters by hand, or import a point file to get one chapter per feature and edit from there. Chapter text is Markdown, so headings, links, emphasis and lists all work.

Crowdsourced Map

The one type you do not supply data for. Visitors drop a pin, fill in a form you designed, and their submission arrives in a moderation queue. Approve it and the pin joins the public map. Community reporting, field surveys, directories, contests, citizen science.

1. Define where pins may go

Whatever you choose is rendered as a spotlight: everything outside the area is dimmed and the allowed region is a clear window, so visitors can see where they are allowed to contribute before they try.

Region searches the same boundary catalog the choropleth map uses — geoBoundaries for countries, states and counties worldwide, and Eurostat NUTS levels across Europe. Pick “Serbia”, or three counties in Germany, and pins are held to the real administrative border rather than a box you eyeball. The boundary is simplified for display, so a pin within a few hundred metres of the border may fall on either side; draw a polygon when you need an exact line.

2. Build the form

Fourteen field types: text, textarea, number, email, URL, date, time, phone, rating, select, radio, multiselect, checkbox and image. Six starter templates — report a pothole, business listing, photo contest, event submission, site review, sighting log — give you a working form to adapt. A live preview shows exactly what visitors will see as you build.

• Validation per field — required, minimum and maximum, maximum length, a regular expression, and how many options a multiselect accepts.
• Conditional fields — show a field only when another one equals, does not equal, has any value, or is empty.
• Multi-step forms — assign fields to steps and visitors get a wizard with a progress bar instead of one long page.

3. Set the rules

4. Emails and webhooks

• You get an email when a submission needs review — and optionally for auto-approved ones too. It links straight to that submission in the dashboard. Send them somewhere other than your account address if you like.
• Visitors can be emailed a confirmation when they submit and a notice when their submission is approved or rejected — both off by default, and both only possible if your form collects an email address.
• Webhooks post JSON to your endpoint on any combination of four events: created, approved, rejected, marked spam. Each request carries an X-Mapji-Signature header — an HMAC of the body using your shared secret — so your receiver can prove it came from Mapji. Failures are retried, and the last deliveries are listed in the editor so you can see what your endpoint actually returned.

5. Choose what the public sees

Compare

Two maps of the same place, locked to the same camera, so a reader can hold one dataset against another. Before and after, plan and reality, two years, two scenarios.

Each side is configured independently and holds its own dataset, imported from its own button in the sidebar.

Importing files

One import pipeline serves every map type. It reads the file server-side, normalises it to WGS84 and hands it to whichever type you are working in — so a Shapefile and a KML behave identically once they are in.

Every one of these works on every map type that imports at all — which is all of them except Crowdsourced Map, whose data comes from visitors.

Google Sheets live sync

Instead of uploading a file, connect a Google Sheet and the map follows it. Your team keeps editing the spreadsheet they already use; the map updates itself. This is the right answer whenever the data has an owner who is not the person who built the map.

1. 1

   Paste the sheet URL

   Any spreadsheet your Google account can read. It does not need to be shared publicly.

2. 2

   Pick the tab

   One tab per map. Mapji lists what the workbook contains.

3. 3

   Map the columns

   Latitude and longitude, plus title and description. A time column for a Time Slider, region and value columns for a Choropleth, a weight column for a Heatmap. Optionally pass every remaining column through as feature properties — do this if you plan to search or filter on them.

4. 4

   Leave it running

   Mapji re-checks the sheet about every five minutes and rewrites the map only when the contents have actually changed. There is a Sync Now button for an immediate pull, and a status widget showing the last successful sync and any error.

Visitor submissions

A Crowdsourced Map gets its own dashboard page for reviewing what comes in. It is laid out like a map editor rather than a report: a list of submissions beside a live map. Clicking a row flies the map to its pin; clicking a pin selects and scrolls to its row. Pins are coloured by status, and the map mirrors whatever filter is active rather than only showing approved pins.

Submissions are rendered against the form as it was when they were made. Change your form later and old submissions still display with the questions their author actually answered, rather than being reshaped to fit the current version.

Limits

Over the feature limit, the usual answers are to aggregate before importing (one row per region rather than per event), to split the dataset across several maps, or to publish it as a background layer, which is fetched live and is not subject to the cap.

Basemap themes

The basemap is what your data sits on. Seven are built in, and switching between them is instant and non-destructive — your data and every setting are untouched. Change it from the Style button on the map.

Vector themes are drawn from OpenStreetMap data via Protomaps; imagery comes from Esri World Imagery. Attribution is rendered on the map automatically.

Custom themes

When none of the seven fits — a brand palette, a print style, a deliberately quiet backdrop — build your own. Custom themes are saved to your account and can be applied to any of your maps from the Style picker, so one theme can carry a whole set of maps. Create and edit them under Settings → Custom Map Styles, with a full live map beside the editor.

Start a custom theme from any of the five vector themes as a base, then override only what you need. Editing a saved theme updates every map using it.

Terrain, 3D buildings & contours

Three optional layers, toggled from the Style button and available on any theme. They work together — terrain with a tilted pitch and contours makes a landscape map, buildings with terrain makes a city one.

Background layers

Draw and Compare maps can render a published map service beneath your own data: aerial imagery, a cadastral layer, a scanned historical sheet, a soil or flood dataset. Nothing is imported — the tiles are fetched live from the publisher every time someone opens your map, so the layer stays current and none of it counts against your feature limit. Add one from the Layers button. On a Compare map each side keeps its own list, so you can put imagery behind one half and a reference layer behind the other.

Interactions

What visitors are allowed to do with the map. All seven are on by default, and they apply to the published map and to embeds — not just the editor preview. There is a Lock all / Unlock all switch for kiosk-style displays and static illustrations.

Map widgets

Which widgets appear on the published map. These also save with the site and apply to visitors, from the Widgets button on the map.

Search & filters

A search and filter panel can be added to most map types, letting visitors search across the fields you choose and narrow the map with faceted filters. It searches your data — the columns you imported — not the world. Mapji has no geocoder, so a query matches feature properties rather than street addresses.

Available on Draw, Cluster, Heatmap, Choropleth, Time Slider, Isochrone and Crowdsourced Map. Store Locator is excluded because its sidebar already has a richer search built on the same engine; Story Map and Compare do not offer it. On a Choropleth the region name and value are searchable as “Region” and “Value”; on an Isochrone the search covers your named origin markers.

Site settings

Four tabs, reached from Settings in the map editor.

Embedding

Every published map has a separate embed URL and a generated <iframe> snippet, built in the Embed tab of Settings. It works anywhere that accepts an HTML embed — a CMS, a blog post, a documentation site, a landing page.