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 mapji.com/map/your-map. Add a subdomain or a custom domain under Settings → Domains, 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 and a colour. On the published map, clicking a marker, line or shape opens a popup with its name and description, shown as plain text — links, images and formatting are not rendered. Lines list their measured length in the sidebar's feature list. Icon markers can have their icon and size changed after the fact from the properties panel.

Routes

A route is drawn along the real road network, not as a straight line between points. Add → Route opens a panel beside the map, and the map stays live: click it to add a stop, click one of your own markers to route through it, or search an address. The route is recalculated as you go, with each leg's distance and time in the stop list. Drag a pin to move a stop, drag the list into a new order, or click a stop's name to search for a different place.

The route's distance and duration are stored on the line and shown in the feature list, where its stops are listed under it. Visitors who click the route see its travel mode, distance, time and number of stops.

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 chart clusters

Pick a property to group by, then define the categories. Each is matched either by Exact values (one or more values from that column) or by a Number range — From one value Up to (not including) another. 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.

A legend on the map lists each category with its colour. Give it a title of your own so readers know what the rings are counting.

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. In the app this type is listed as Region Map.

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. In the app this type is listed as Travel Time Map.

Place starting points by clicking the map, or import a point file and tick the rows that should become starting points — up to five. Bands are drawn as nested translucent polygons, colour-coded from nearest to furthest, over any basemap, and a legend lists each band with its colour. The zones show how far people can get, not how many of them live inside — Mapji does not count population or addresses within a band.

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. Every word has to match, in any field, and accents are ignored — “pharmacy leeds” finds the Leeds pharmacy, “cacak” finds Čačak. It is a keyword match, not an address lookup: a postcode only finds locations that carry it in their data. Turn on town or postcode search (off by default) and pressing Enter looks the typed text up as a place instead — the list then sorts by distance from it, nearest first, under a “Nearest to …” chip. Your locations still need coordinates: only the visitor's one typed place is looked up, near your locations, and it isn't stored. Near Me, below, answers “nearest to me”. On top of that you define faceted filters from your own columns:

• Select — a column with up to 10 values, shown as a row of toggle pills (pick one or several).
• Multi-select — up to 30 values, also as toggle pills, 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, decimals included.
• Open now — offered to visitors automatically once a working-hours column is set, narrowing the list to locations open at that moment.

Filter choices are read from your current data, so a category that arrives with the next sync or import appears on its own. Turn on Zoom to results (off by default) and the map fits itself to the matching locations once a visitor searches or filters.

Any one filter can also drive the map: nominate it and each of its options gets its own marker icon, in any colour, so branches, kiosks and warehouses are distinguishable at a glance without opening anything — and a legend of those icons can sit on the map. Markers can be the bare icon, the icon on a white badge, a dot, or a pin with the icon inside.

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 moves 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. Images are uploaded straight from the chapter editor — the button, a paste or a drop — as PNG, JPEG, GIF or WebP up to 10 MB; large photos are scaled down first. A Write / Preview toggle shows the chapter as readers will see it.

Readers can scroll, click a marker or a progress dot, or use the keyboard: ↓ → Page Down or j for the next chapter, ↑ ← Page Up or k for the previous one, Home and End for the first and last. Every chapter has its own link — add #chapter-3 to the map's address to open the story at chapter 3, and the address follows the reader as they go. For readers who ask their device for reduced motion, camera moves become cuts and text no longer slides or scales in.

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 — the editor's Pins tab. 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: Short text, Long text, Number, Email, URL, Date, Time, Phone, Rating, Dropdown, Radio, Multi-select, 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 Multi-select 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, opened in the map editor. 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

You review what comes in on the Pins tab of the map editor, where its count of pending submissions shows. It lists every submission, whatever its status, beside the live map. While the tab is open the map shows those submissions rather than only the approved pins: each is coloured by its status, and the map follows whatever filter is active. Clicking a row flies the map to its pin; clicking a pin selects and scrolls to its row. The other tabs go back to showing the map as visitors will see it.

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. The credits for the basemap, the terrain and any background layers are shown in the map's bottom-right corner automatically, on your public map and in embeds alike.

Custom map styles

When none of the seven fits — a brand palette, a print style, a deliberately quiet backdrop — build your own. Map styles are saved to your account and can be applied to any of your maps from the Style picker, so one style 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 style from any of the five vector themes as a base, then override only what you need. Editing a saved style updates every map using it.

Map features

Four optional layers, toggled from the Map Features list in 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, and points of interest give either its landmarks.

Background layers

Every map type 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.

The quickest way in is the Browse layers catalog: public layers we have checked work on any site and may be used on commercial maps, added with one click — no URL needed. Each one brings its own zoom range, coverage and credit.

Daily layers show the most recent complete day, and catalog layers stay pointed at their publisher's current address without you doing anything. If you have a service of your own, use Paste a URL:

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.

Popups

Clicking a feature opens a popup. Until you change it, each map type shows its built-in one — a marker's name and description, a region's value, every column of a clustered point. Under Popup in the Settings tab you can design it instead: which column titles it, which rows it lists, in what order, under what label and in what format. A preview beside the settings shows the result for your real features as you edit — step through them with the arrows. Search results open the same popup.

Available on Draw, Cluster, Heatmap, Choropleth, Time Slider and Crowdsourced Map. Store Locator keeps its own location cards, set up under its display fields; Isochrone, Story Map and Compare show their own popups. On a Crowdsourced Map the popup is in the Display tab, offers only the fields you publish, and opens only when approved pins are shown with details. On a Draw map, clicking in the editor selects a feature, so use the preview.

Text and numbers can carry words before and after them — m², /night, approx. — spaced the way they read: 120 m², €90/night. Any row can hide its label. When you pick Customize, years, postcodes, ids, phone numbers and coordinates start as text, so they never gain thousands separators or lose a leading zero.

Rows with no value are skipped, and a value that doesn't fit its format — text in a currency column, a link that isn't a web address — is shown as plain text rather than guessed at. You can also switch popups off, or reset to the built-in popup. On a Time Slider, the popup fields you chose before this existed keep working until you customize the popup here.

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. It never looks addresses up, 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 has its own search, which matches every word in any field; 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 starting points.

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.