GeoJSON · format guide
GeoJSON viewer online
GeoJSON is a JSON FeatureCollection where geometry sits alongside arbitrary properties. MapCrafter reads points, lines, polygons and mixed collections, offers the properties as fields for colour and labels, and renders everything on vector tiles. Because it is already the renderer’s native format, nothing is converted.
What a GeoJSON file is
GeoJSON is the lingua franca of web mapping and the format every other format gets converted into. A FeatureCollection holds Features, each with a geometry and a properties object, and the properties are what make it useful: they are the columns, and they can drive colour, size, labels and popups directly.
Because MapCrafter renders GeoJSON natively, an imported file keeps its properties exactly as written, including nested objects and arrays. There is no round trip through a database schema, so nothing is renamed, truncated or dropped.
The common difficulties with GeoJSON are practical rather than conceptual: files that are enormous because coordinates have fifteen decimal places, collections that mix geometry types, and coordinates in the wrong axis order. The first is fixable by quantising, the second is handled on import, and the third is the single most common reason a GeoJSON file appears on the wrong side of the world.
What MapCrafter reads from it
- FeatureCollection
- The normal container, with any mix of geometry types
- A bare Feature or geometry
- Wrapped automatically rather than rejected
- Nested properties
- Objects and arrays are kept and can be shown in popups
- Mixed geometry
- Kept in one layer, with a renderer for each geometry type present
- Feature ids
- Preserved, which keeps a round trip through export lossless
Mapping a GeoJSON file, step by step
- 1
Drop the .geojson or .json file in
The file is parsed and features are counted before anything renders.
- 2
Check the geometry mix
A mixed collection stays in one layer: polygons fill, lines stroke and points get markers. Use separate source files for independent layer controls.
- 3
Style from the properties
Any property can drive colour categorically or sequentially, or scale marker size.
- 4
Export it back out
Export retains imported feature properties and adds an _layer property naming the source layer.
Things that go wrong with GeoJSON
Every one of these is a property of the format rather than a bug in a particular tool, which is why they keep happening.
Everything is mirrored or off the coast of Somalia.
Axis order. The specification says longitude first, but a lot of code writes latitude first because that reads naturally. If your points are mirrored across the diagonal, the two are swapped.
The file is 200 MB and the browser struggles.
Coordinate precision. Fifteen decimal places is sub-micron on the ground and roughly doubles the file. Six decimal places is about 10 cm, which is plenty for anything short of surveying. Quantise with mapshaper or tippecanoe before importing.
Nothing renders and there is no error.
Usually a valid JSON file that is not GeoJSON — a TopoJSON file, a bare array of coordinate pairs, or a FeatureCollection with a null geometry on every feature. Check the top-level "type" member.
Polygons have hairline gaps between neighbours.
Two adjacent polygons each draw their own edge, and the antialiasing of both is visible. The standard fix is what MapCrafter does by default: draw the outlines in the land colour beneath the fills so the seams disappear.
Properties are missing after a round trip through another tool.
Some tools only preserve properties they recognise, and Shapefile in particular truncates names to ten characters and drops types it cannot express. Going GeoJSON to Shapefile to GeoJSON is lossy in a way that is not obvious.
GeoJSON maps in the gallery
14 live maps built from GeoJSON data, each showing its source columns and the geometry that was detected.
- ChoroplethPopulation across Europe, country by countryA continent cut from the same world boundary set, filled from a two-column table. Countries the table has no row for stay grey, so a gap in the data is visible rather than filled in.
- ChoroplethPopulation across Asia, country by countryThe most populous continent as a choropleth, with the two extremes — China and India against the smaller states — handled by the ramp rather than flattening everything into one colour.
- ChoroplethPopulation across South AmericaCountries and territories across the continent, filled by population. A small enough set that every shape is legible at once, which makes it a good demonstration of a choropleth with no outliers to hide behind.
- ChoroplethPopulation across OceaniaPacific countries and territories spread across a vast ocean, which is the case that shows why a region map needs a camera of its own rather than a fit to its bounds.
- ChoroplethWorld population as a choroplethA choropleth of world population built from a two-column table of country names and values. Countries with no matching row are drawn in grey rather than dropped, so the gap in the data is visible instead of hidden.
- Proportional symbolA sensor network coloured by readingPoint data coloured on a sequential ramp, one marker per station. Sequential colour on symbols works when the markers are large enough to compare; below about eight pixels, size or clustering carries the signal better.
- HexbinAgricultural survey binsA wide, sparse region binned at a coarse cell size. Cell size is the single most consequential choice in a binned map: too small and the pattern dissolves into noise, too large and the structure vanishes into a single blob.
- Dashed coverage zonesDelivery zones with overlapsOverlapping zones drawn at partial opacity on a dark basemap. Where two zones overlap the fill deepens, which turns a coverage map into a map of contention without adding a single extra layer.
- Location pinsBike stations across LondonA GeoJSON FeatureCollection with properties used directly. GeoJSON is the one format that already speaks the renderer’s language, so the only real decision left is how to style it.
- ChoroplethPopulation across AfricaA continental focus where the frame is set to Africa rather than the whole world. Choosing the frame is a cartographic decision, not a cosmetic one: a map of Africa cropped to its own bounds uses roughly three times the pixels for the same information.
- ChoroplethPopulation across CanadaAll ten provinces and three territories, filled with 2021 census population. Quantile classes make the northern territories visible while preserving their real values in the popup and the numeric key below the map.
- Continuous heatmapContinuous heat across San FranciscoWeighted source points blend into a continuous density surface instead of separate grid cells. The colour shows relative concentration at the current zoom, while the radius and intensity remain editable in the studio. All observations in this example are simulated.
- Distance bandsDistance bands around Austin service hubsThree distance bands distinguish local, intermediate and extended reach around each service hub. The outer rings have holes, so colours do not stack within a single hub. These are straight-line distance buffers and do not represent driving times or official service boundaries.
- Multi-symbol markersFacility types marked by shape in New YorkPins, triangles and squares distinguish three types of facility, with colour providing a second cue. Each group is a separate editable layer with names and popups. The example uses hypothetical facilities to demonstrate a multi-symbol map without claiming to be a real service directory.
GeoJSON questions
- How do I view a GeoJSON file without writing code?
- Drop the file into the studio. It is parsed in the browser and rendered on a vector basemap, with the properties offered as fields for colour, labels and popups. Parsing happens locally; basemap requests still use the network.
- Does MapCrafter handle TopoJSON as well?
- Yes. TopoJSON is detected and converted, which is worth knowing because topology stores shared arcs once, so a TopoJSON file is often a fifth the size of the equivalent GeoJSON.
- Can I edit the properties?
- Not yet. You can style by them and export them unchanged, but editing attribute values in the browser is on the roadmap rather than shipped.
- What happens to a mixed FeatureCollection?
- It stays in one mixed layer, with points, lines and polygons drawn using the applicable parts of its style. Import separate files when you need independent visibility, colour or popup settings.
Other formats MapCrafter reads
Start with your own fileLast updated 2026-10-22.