CSV · format guide
CSV to map
MapCrafter reads a CSV or TSV file, works out where the geometry is, and draws it as points, lines or areas. It accepts a latitude and longitude pair, a WKT or GeoJSON geometry column, or an address column it will geocode. Delimiters are detected and quoted fields are handled, so most exports work untouched.
What a CSV file is
A CSV is the most common way location data leaves another system: an export from a database, a download from a dashboard, a spreadsheet saved as plain text. The awkward part is that CSV has no concept of geometry, so the coordinates are just more columns and something has to decide which ones matter.
MapCrafter profiles every column on import. Numeric columns that look like latitudes and longitudes are paired; a text column containing WKT or GeoJSON is parsed as geometry; a column of street addresses is offered for geocoding. The import report explains what was detected and any rows that could not be placed. Correct the source columns and re-import if the inferred geometry is wrong.
Everything after that is the same as any other format: pick a basemap theme, choose which column drives colour or size, and export or share.
What MapCrafter reads from it
- Latitude and longitude columns
- Named lat/lon, latitude/longitude, y/x, or detected by value range
- A single coordinate column
- Values like "47.3769,8.5417" or "8.5417 47.3769"
- WKT geometry
- POINT, LINESTRING, POLYGON and their multi- variants
- A GeoJSON geometry column
- A JSON object in a cell, which is what PostGIS and BigQuery exports produce
- Street addresses
- Address rows are retained; run geocoding from the selected layer inspector
- Region-value tables
- Not automatically joined to boundaries. Import polygons with their values already attached
Mapping a CSV file, step by step
- 1
Check your headers
The first row should be column names. If your file has no header row the first record is read as data instead, which is usually what you want.
- 2
Drop the file into the studio
Delimiter, quoting and encoding are detected. You will see the column list and what geometry was inferred.
- 3
Confirm the geometry
Check the import report. Correct the source headers if needed; address rows require an explicit geocoding step.
- 4
Style it
Choose a colour ramp for a category or a numeric column, and optionally size points by a value.
- 5
Share or export
Publish a short link, embed it, or export a PNG or the cleaned-up GeoJSON.
Things that go wrong with CSV
Every one of these is a property of the format rather than a bug in a particular tool, which is why they keep happening.
The first column name shows up as "id" or similar garbage.
That is a UTF-8 byte order mark, which Excel writes when you use "CSV UTF-8". MapCrafter strips a leading BOM automatically, but if you are processing the file elsewhere, strip the first three bytes.
Every row landed in one column.
Excel in a European locale exports semicolons rather than commas, because the comma is the decimal separator. Delimiters are detected from the header line, so this usually just works; if it does not, export as TSV instead.
Latitude and longitude came out swapped.
The giveaway is points landing off the coast of Somalia, near 0, 0, or latitudes above 90. If a "latitude" column contains values greater than 90 they are longitudes. Swap them in the geometry step rather than editing the file.
Coordinates are in a projected system, not degrees.
Values in the hundreds of thousands are metres in a projected CRS such as Web Mercator or a national grid, not degrees. CSV carries no projection information, so convert to WGS84 first or supply the data as a Shapefile with a .prj.
A numeric column arrived as text and will not colour.
Usually a stray currency symbol, thousands separator or non-breaking space. Numeric strings that parse cleanly are treated as numbers; anything else is offered as a category instead.
Dates render as five-digit numbers.
That is the Excel serial date leaking through a CSV export. Multiply by 86400 and offset from 1899-12-30, or export the column as an ISO date string instead.
CSV maps in the gallery
21 live maps built from CSV data, each showing its source columns and the geometry that was detected.
- ChoroplethInternet penetration by countryPercentage of the population online, drawn as a single-hue sequential choropleth. One hue with varying lightness is the correct choice when the data has a natural zero, because readers can rank areas without consulting the legend.
- ChoroplethPopulation by US stateAll fifty states plus DC and Puerto Rico, filled from a state-name column. State outlines come from Census cartographic boundaries, so the shapes match what people expect from an official map.
- Proportional symbolMetro areas sized by populationProportional circles for the world’s largest metro areas. Symbol area scales with the value, not the radius, which is the difference between a map that communicates magnitude and one that exaggerates it by a factor of four.
- Classified sensor symbolsAir quality stations across EuropeSensor readings on a sequential colour scale, so brighter marks reveal higher simulated measurements. Larger station symbols keep each city cluster visible at a continental scale, while the legend states the numeric intervals used by the colours.
- Route mapFlight routes from an origin-destination tableRoutes drawn from a table with from and to columns, matched against a built-in place index. Origin-destination tables are the most common shape of transport data, and requiring pre-built line geometry rules out most of it.
- HexbinBinned density over LondonTen thousand observations would overplot into a solid blob. Binning them into hexagons aggregates first and colours second, which is the only way a reader can see where a dense point dataset actually concentrates.
- HexbinTokyo binned densityA dark-theme hexbin over the Kantō plain, with the highest-value cells reaching a pale yellow. On a dark basemap the ramp has to run towards light, because a dark-to-dark ramp has nowhere left to go.
- HexbinBinned density across IndiaBinned observations over a large, irregular landmass. Because cells are generated in geographic space, a binned map over a wide latitude range needs its cell size expressed in kilometres, not degrees.
- Facility catchmentsHospital catchment areasCatchment polygons drawn around facility points. Catchments are the most common polygon a non-GIS user needs, and generating them from a radius is faster and more reproducible than tracing boundaries by hand.
- Graduated circlesA tree inventory as a categorical point mapPoint data coloured by species category. Categorical colour is the hardest palette to get right: two categories that look alike are not a cosmetic problem, they are two categories the reader will merge into one.
- Categorical pointsFour hundred inspections across New YorkA dense point layer on a dark basemap, where marker opacity and stroke width do the work that colour cannot. Past a few hundred markers, the marks must be translucent or the map becomes a solid mass.
- Classified diamondsAir quality monitoring in BerlinClassified diamond markers encode a numeric reading, which is often more useful than a raw number alone. Converting a continuous measurement into bands is a modelling decision, so the thresholds belong on the map, not buried in a spreadsheet.
- Survey gridA bathymetric survey gridSquare cells for a survey where the measurement grid itself is square. Squares are the honest choice when the sampling geometry is square; hexagons are the honest choice when it is not. The grid should look like the method.
- Survey gridSoil samples on a survey gridA regular sampling grid with a diagonal gradient, drawn with hairline cell borders. Borders between adjacent cells of the same class add visual noise, so they are drawn at the minimum width that still separates classes.
- Proportional symbolSouth American citiesLabelled city points with collision avoidance, sized by metro population. Labels are the most expensive thing on a map: they must be large enough to read, few enough to not overlap, and placed so they describe the mark they belong to.
- Point mapNordic citiesA sparse point layer where each mark can afford to be generous. When a map has fewer than fifty marks, larger symbols and labels cost nothing and make the map readable at a glance rather than requiring study.
- Network mapAviation hubs and their routesTwo layers from one dataset: hubs as points, connections as lines, drawn in a single coordinated view. Layering is what turns a plot into an argument, and it is the reason a layer tree rather than a single style dialog is the right interface.
- Point mapAustralian coastal citiesA handful of coastal cities on a light theme, with the frame chosen to show how concentrated the population is. A map that shows emptiness is doing its job: the sparse interior is the finding.
- ChoroplethPopulation across Brazil’s statesA map of Brazil’s 26 states and the Federal District, joined to IBGE’s 2022 census population. Six quantile classes separate the sparsely populated northern states from the populous southeast without hiding either behind a flat fill.
- Network mapA route network across Southeast AsiaCurved connections between island cities, where straight lines would cross water misleadingly. On an archipelago, the curve is not decoration: it distinguishes a route that follows a corridor from one that implies a land connection.
- Dot densityDot density across ChicagoSmall translucent dots show the source observations themselves. Dense clusters become darker through overlap while isolated observations stay visible, offering a useful alternative to continuous smoothing or cell aggregation. Each dot is one synthetic record rather than a population conversion.
CSV questions
- How do I plot latitude and longitude from a CSV on a map?
- Put the file in the studio. Columns named lat and lon, latitude and longitude, or y and x are paired automatically, and a pair is also detected by value range when the names are unhelpful. You then choose the styling and export or share.
- Can MapCrafter map a CSV that only has addresses?
- Yes. An address column is detected and offered for geocoding on import. You can also bring your own MapTiler or Mapbox key to use your own provider quota instead of the shared one.
- What is the largest CSV I can map?
- Practical limits depend on browser memory, geometry complexity and graphics capacity. A server-saved map is limited to 12 MB of serialised data. Try a sample first; simplify large geometry or prepare aggregate cells outside the studio when appropriate.
- Is my CSV uploaded to a server?
- Parsing happens locally. Saving or publishing uploads the map document, including its geometry and properties. Geocoding sends address text to the chosen service. The original CSV is not uploaded for parsing.
- Which delimiters are supported?
- Comma, semicolon, tab, pipe and colon are all detected from the header line. Quoted fields containing the delimiter, embedded newlines and doubled quotes are handled, which is what RFC 4180 requires.
Other formats MapCrafter reads
Start with your own fileLast updated 2026-10-22.