In order to make maps with React Simple Maps, you will need a working map file. Usually you will want to tailor your own map files for your specific application. This guide will give you a high-level overview of what to look out for and where to get started.

Common file formats in cartography

Geographic data comes in many container formats. Here are the ones you are most likely to run into:

• GeoJSON (.json, .geojson) — JSON-based, human-readable, natively consumed by the browser
• TopoJSON (.json, .topojson) — GeoJSON extension that encodes topology; much smaller than regular GeoJSON
• Shapefile (.shp + .dbf) — the Esri legacy standard; a multi-file binary bundle
• GeoPackage (.gpkg) — OGC standard, a single SQLite database
• KML (.kml, .kmz) — XML-based, from Google Earth

For SVG cartography on the web, GeoJSON and TopoJSON are the standard. They are plain JSON, so they don't need to be decoded in the browser. Both are what d3-geo — the projection library at the core of React Simple Maps — expects as input.

GeoJSON

GeoJSON defines different geometry types — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection — plus Feature and FeatureCollection wrappers that attach properties to a geometry. Coordinates are longitude/latitude in WGS 84 decimal degrees.

Every geometry stores its own coordinates independently. That makes the format simple, but redundant: the border between two neighbouring countries is written out twice, once for each side.

TopoJSON

TopoJSON is an extension of GeoJSON that encodes topology. Instead of storing each geometry separately, it stitches geometries together from shared line segments called arcs.

Advantages over GeoJSON:

• Smaller files. Because shared borders are stored only once, TopoJSON files are significantly smaller than their GeoJSON counterparts.
• Delta-encoded integer coordinates. Quantization stores coordinates as integer deltas, shrinking the file further with explicit control over precision loss.
• Topology-preserving simplification. Simplifying a TopoJSON keeps adjacent features connected (avoiding slivers and unwanted gaps between neighbours) and stays consistent even across feature collections, so state and county boundaries simplify together.

The tradeoff is that TopoJSON must be converted back to GeoJSON before rendering. That is a single cheap call to topojson-client's feature(). React-simple-maps handles this conversion automatically if you give it a link to a valid topojson file or a topojson object.

Converting from other formats

Shapefiles and other GIS formats convert to GeoJSON/TopoJSON easily. You can do this either on the CLI with a tool like shapefile, or you can use an online tool like mapshaper.The latter is particularly useful if you are planning to do additional work (simplification, feature editing etc.) and you want some visual feedback. Mapshaper also has a CLI tool.

Where to get map files

Good generic map files can be hard to source. Unfortunately none of the easily accessible and open sources online at the moment are ready to be used in web cartography out of the box. They all require some additional work to be usable.

Here is a list of recommended sources and how they need to be prepared to be used for web cartography:

• geoBoundaries CGAZ — CC BY, but the base version is 400MB so needs to be simplified for web mapping (e.g. with mapshaper)
• GISCO CNTR — global, authoritative, but non-commercial use only license
• UN Geodata — Earth Engine registration necessary for access (Google sign in) — The data is free to use for research, education, and non-profit applications
• Natural Earth — Accessible, public domain, but you have to be careful about POV here (e.g. US POV) — Needs additional simplification

For the purpose of learning how to map with React Simple Maps, you can use the GISCO CNTR map files. They are easy to access and download. When configuring the download, make sure to select TopoJSON at 60M and in the EPSG:4326 (WGS 84) coordinate reference system. If you are doing non-commercial work, you can consider this a very good solution (don't forget the correct attribution).

If your maps will be deployed in a commercial setting, you can use the geoBoundaries CGAZ files and simplify them manually using a tool like mapshaper. This is fairly straightforward, it just adds an additional preparatory step. Generally, you should aim for map files below 1MB in size.

Keep in mind that most of these maps represent the US/European point of view, so if you need something different, you can check out Natural Earth, which offers a variety of POVs for different mapping needs.

Downloads

To get started quickly, we offer a set of starter map files to work with for the world map and US states and counties. You can use these map files for the quickstart tutorials and you can also use them in production.

The US states and counties files are derived from TopoJSON US Atlas. The borders are the same, the files are just structured differently to make them easier to work with in React Simple Maps. The original files have "layers", the files here are just one layer of geometries per file.

Note that the above maps represent the US point of view derived from Natural Earth (simplified to be smaller in size), so if you need maps that express a different set of borders and divisions, you can check the Natural Earth repository on github. They have a lot of other options there.