Skip to content
MangoMap Help Centre
Esc
↑↓navigate↵open⌘Jpreview
On this page

How importing data works in MangoMap

What happens after you click Save on an import, why MangoMap reprojects data to Web Mercator, and which column names it changes and how.

When you import data, MangoMap stores it in your account library as a dataset, then makes it available to draw on any map as a layer. This page explains these terms, what happens after you click Save, and why MangoMap changes the projection.

Datasets and layers

A dataset is a copy of your data inside your account library. It lives at Data in the main navigation, and it’s independent of any particular map. A layer is that dataset placed on a specific map, carrying its own styling and visibility. One dataset can power layers on many maps. For the full picture — what belongs to the dataset versus the layer, and why removing a layer keeps the data — see Datasets and layers in MangoMap.

This split matters when you import:

  • Importing from the Data page adds the file to your library only. You attach it to maps later.
  • Importing from a map (Manage layers → Import new data) does both at once — uploads the dataset and adds it as a layer on that map.

What happens after you click Save

Your files upload as soon as you add them. When you click Save, MangoMap processes them:

  1. The page shows a Processing data… dialog while MangoMap prepares the dataset.
  2. MangoMap reads your file and prepares the data.
  3. On success, you land on the dataset page (or back on the map with the new layer added). On failure, the dialog switches to Processing failed with an error message and a Try again button. Try again clears the form, so you add the files again.

Processing time depends on the file size and complexity. Closing the tab does not cancel processing, and the dataset still appears in your library when it is ready. But the page can’t show you the result, and if you started from a map, the layer is not added to it.

Follow an upload through these states to see where it can fail and where Try again takes you:

What happens to an upload State machine: files upload as you add them; Save starts processing on MangoMap’s servers, which reads and prepares your data, and closing the tab does not stop this; it ends on the dataset page or the map, or at Processing failed, where Try again returns to an empty form. PROCESSING DATA… SAVE ERROR SUCCESS TRY AGAIN Uploading as you add each file ProcessingMangoMap reads your fileand prepares the data Runs on MangoMap’s servers: closing the tab doesn’t stop it. Processing failedshows the error anda Try again button Done opens the dataset page, or the map with the layer

Why MangoMap reprojects to Web Mercator

MangoMap converts your data to match the basemap, so you never pick a coordinate system. It reads the one your file declares:

  • For a shapefile, that’s the .prj file.
  • For GeoJSON, the crs field if present, otherwise EPSG:4326 per the spec.
  • For other vector formats, whatever the file declares internally.

If MangoMap finds no coordinate system with a code, such as EPSG:27700, it assumes EPSG:4326 (WGS84). If the file names a system MangoMap can’t convert from, processing fails with an Unsupported coordinate system error and you’ll need to reproject the file in another tool first. See Unsupported coordinate system.

The diagram shows which system MangoMap converts from, and the one case that fails:

Which coordinate system MangoMap converts from Flowchart: MangoMap reads the coordinate system from the .prj file, the GeoJSON crs member or the file itself; with no code it assumes EPSG:4326; a system it can’t convert from fails with Unsupported coordinate system; everything else is stored in EPSG:3857 without the original coordinates. NO YES YES NO MangoMap reads your file .prj file, GeoJSON crs, or the file itself Coordinate systemwith a code? Assumes EPSG:4326WGS84 Can MangoMapconvert from it? Processing failedUnsupported coordinate systemreproject the file first Stored in EPSG:3857Web Mercator; the originalcoordinates are not kept

MangoMap does not keep the original coordinates with the Web Mercator copy. If you need to keep the source projection, keep your original file outside MangoMap.

Reserved field names

These five column names are reserved for system use. If a column in your file has one of them, in any mix of upper and lower case, MangoMap renames it on import by adding a leading underscore:

Source name Stored as
gid _gid
geom _geom
id _id
geometry _geometry
the_geom _the_geom

This is the full list. It applies to every vector and tabular format (CSV, GeoJSON, KML, Shapefile, TAB, Geo database).

CSV coordinate columns

A CSV has no geometry, so MangoMap makes each row’s point from two columns. It looks for these names, in any mix of upper and lower case:

Coordinate Column names
Longitude Longitude, Lon, Long, Lng, X, Longtitude
Latitude Latitude, Lat, Y

The first matching column from the left is used for each. Those two columns become the point’s location and are not kept as attributes, so they do not appear in the data table, the popup, or the style field lists. Another column that also matches, such as X when Longitude is used, stays an ordinary attribute.

To keep the coordinates as attributes, add a copy of each column with another name, such as lon_value and lat_value, before you import. The values must be decimal degrees (WGS 84). See How to import a CSV.

Other column name changes

MangoMap also changes a column name that is not a valid database name. In this order, it:

  1. Removes spaces at the start and end.
  2. Replaces each run of spaces with one underscore: Land use becomes Land_use.
  3. Removes every character that is not a letter, a digit, or an underscore: Cost (€) becomes Cost_.
  4. Adds a leading underscore to a name that starts with a digit: 2020 population becomes _2020_population.
  5. Adds a leading underscore to a reserved name (see above).

For every format, the stored name is also lower case: Shape_Leng becomes shape_leng.

If two columns end up with the same name, ignoring case, the import stops with Duplicate column names found after sanitization, followed by the names. Rename those columns in your file so each name is unique, then import it again.

Follow one column name through every rule to see what MangoMap stores:

How a column name is cleaned up Process: the column name “ 2020 Pop. (%)” is trimmed, its spaces become underscores, its symbols are removed and it gets a leading underscore for the digit, giving _2020_Pop_; the reserved-name rule leaves it unchanged; if another column now has the same name, ignoring case, the import stops, otherwise it is stored in lower case as _2020_pop_. YES NO The name in your file 1Trim spaces at the ends 2Turn spaces into _ 3Remove other symbols 4Starts with a digit: add _ 5Reserved name: add _ " 2020 Pop. (%)" "2020 Pop. (%)" "2020_Pop._(%)" "2020_Pop_" "_2020_Pop_" no change Same as anothercolumn’s name? Import stops Duplicate column names found after sanitization Stored in lower case "_2020_pop_"

Where you see the new name

MangoMap keeps the original name as the column’s display name, so the style field lists and the legend still show id. The data table, popup variables ({_id}), downloads, and anything that reads the data from outside MangoMap use the stored name. If you reference the column from outside MangoMap, use the stored name.

This also matters when you upload a new file to update an existing dataset — see What can break in the data updates concept page.

Common confusions

“Why is my data showing up in the wrong place?” — Usually a coordinate-system problem. The file declared the wrong projection, or had no projection information and MangoMap defaulted to WGS84. For shapefiles, check that the .prj was uploaded with the others. For GeoJSON, confirm the file is in WGS84.

“I deleted the layer but the dataset is still there.” — That’s expected. Layers and datasets are independent. To remove the data entirely, delete the dataset from the Data page.

“I uploaded the same shapefile twice and got two datasets.” — MangoMap does not deduplicate by content. Each import produces a new dataset.