Edit and Join with Mapshaper

Like GeoJson.io, Mapshaper is a free, open-source editor that can convert geospatial files, edit attribute data, filter and dissolve features, simplify boundaries to make files smaller, and many more. Unlike GeoJson.io, Mapshaper doesn’t have drawing tools, so you won’t be able to create geospatial files from scratch.

Mapshaper is developed and maintained by Matthew Bloch on GitHub. It is written in JavaScript, so we recommend you use a recent version of Firefox or Chrome.

This free and easy-to-learn Mapshaper web tool has replaced many of our map preparation tasks that previously required expensive and hard-to-learn ArcGIS software, or its free but still-challenging-to-learn cousin, QGIS. Even advanced GIS users may discover Mapshaper to be a quick alternative for some common but time-consuming tasks.

Import, convert, and export map boundary files

You can use Mapshaper to convert between geospatial file formats. Unlike GeoJson.io, Mapshaper also supports Esri Shapefiles (which is a folder of individual files with the same name, but different file extensions), so you can easily convert a Shapefile into a web-friendly GeoJSON. In the following steps, we will convert a geospatial file by import it to Mapshaper, and then export it as a different file type.

  1. Navigate to Mapshaper.org. The start page is two large drag-and-drop zones which you can use to import your file. The smaller area at the bottom, Quick import, uses default import settings and is a good way to begin.
  2. Drag and drop your geospatial file to the Quick import area, or use our sample Shapefile of US state boundaries. This is a .zip archive which contains a folder with all necessary files.

Note: If you want to import a folder, you need to either select all files inside that folder and drop them all together to the import area, or create a .zip archive.

  1. Each imported file becomes a layer, and is accessible from the dropdown menu in the top-middle of the browser window. There, you can see how many features each layer has, toggle their visibility, or delete them.
  2. To export, go to Export in the upper-right corner, and select a desired file format. The choice of export formats is shown in Figure 14.11. As of July 2020, these are Shapefile, GeoJSON, TopoJSON (similar to GeoJSON, but with topographical data), JSON records, CSV, or SVG (Scalable Vector Graphics, for web and print). If you export more than one layer at a time, Mapshaper will archive them first, and you will download an output.zip that contains all exported layers.
You can use Mapshaper to quickly convert between geospatial file formats.

Figure 14.11: You can use Mapshaper to quickly convert between geospatial file formats.

Tip: Mapshaper doesn’t work with KML or KMZ files, but you can use GeoJson.io to convert these.

Edit data for specific polygons

You can edit attribute data of individual polygons (and also points and lines) in Mapshaper. Figure 14.12 shows you how.

  1. Import the file whose polygon attributes you want to edit.
  2. Under the cursor tool, select edit attributes.
  3. Click on the polygon you want to edit. A pop-up will appear in the upper-left corner listing all attributes and values of the polygon.
  4. Click on any value (underlined, in blue) and edit it.
  5. When you are done, export your geospatial file by clicking Export and choosing the desired file format.
Use edit attributes tool (under Cursor tool) to edit attributes of polygons, lines, and points.

Figure 14.12: Use edit attributes tool (under Cursor tool) to edit attributes of polygons, lines, and points.

Simplify map boundaries to reduce file size

You may not need precise and detailed map boundaries for data visualization projects where zoomed-out geographies are shown. Detailed boundaries are heavy, and may slow down your web maps.

Consider two maps of the contiguous US states (also known as the lower 48, the term Ilya learned in 2018 while travelling in Alaska), shown in Figure 14.13. The map in Figure 14.13a is more detailed and is about 230 kilobytes, but the map in Figure 14.13b is only 37 kilobytes, 6 times smaller!

Consider simplifying geometries with Mapshaper to make your web maps faster.

Figure 14.13: Consider simplifying geometries with Mapshaper to make your web maps faster.

To simplify map boundaries in Mapshaper, follow the steps below.

  1. Import your geo file to Mapshaper. You can use the sample contiguous US states GeoJSON.
  2. Click the Simplify button in the upper-right corner. The Simplification menu will appear, where you can choose one of three methods. We recommend checking prevent shape removal, and leaving the default Visvalingam / weighted area. Click Apply.
  3. You will see a slider with 100% appear on top (Figure 14.14), replacing the layer selection dropdown. Move the slider to the right and see the map simplify its shape as you go. Stop when you think the map looks appropriate (when the shapes are still recognizable).
  4. Mapshaper may suggest to repair line intersections in the upper-left corner. Click Repair.
  5. You can now export your file using the Export feature.
Use Simplify & Repair tools in Mapshaper.

Figure 14.14: Use Simplify & Repair tools in Mapshaper.

Tip: You may find the US shape a bit unusual and vertically “shrunk”. In Console, type -proj EPSG:3857 to change projection to Web Mercator, which is more common.

Dissolve internal polygons to create an outline map

Mapshaper’s most powerful tools are available through the Console, which allows you to type commands for common map editing tasks. One of such tasks is to create an outline map by removing the internal boundaries. For example, you can dissolve state boundaries of the US map in the previous exercise to get the outline of the country, like is shown in Figure 14.15.

Mapshaper lets you dissolve boundaries to create an outline shape.

Figure 14.15: Mapshaper lets you dissolve boundaries to create an outline shape.

Click the Console button, which opens a window to type in commands. Enter the command below, then press return (Enter).


You will see that internal boundaries became lighter color, and that’s Mapshaper’s way of saying they no longer exist. You can now export your outline shape.

Clip a map to match an outline layer

The state of Connecticut consists of 8 counties, which in turn are divided into towns. There are a total of 169 towns in Connecticut. Imagine you are given a boundary file of all 169 towns, and the outline of Hartford county. You need to “cut” the original towns map to only include those towns that fall within Hartford county.

Mapshaper allows you to do just that using one simple -clip command.

  1. Import two boundary files into Mapshaper. One is the larger one that is being clipped (if you use sample files, ct-towns), and one is the desired final shape (hartfordcounty-outline). The latter is what ArcGIS calls the “clip feature”.
  2. Make sure your active layer is set to the map you are clipping (ct-towns).
  3. In the Console, type -clip followed by the name of your clip layer, like that:
-clip hartfordcounty-outline
  1. You should see your active layer got clipped. Sometimes you end up with tiny “slivers” of clipped areas that remain alongside the borders. If that is the case, use the -filter-slivers command to remove them, like that:
-clip hartfordcounty-outline -filter-slivers
  1. Your Mapshaper state should look like pictured in Figure 14.16. You can now save the file on your computer using the Export button.
When clipping, make sure your active layer is the one being clipped (with many features), not the clipping feature iteslf.

Figure 14.16: When clipping, make sure your active layer is the one being clipped (with many features), not the clipping feature iteslf.

Remove unwanted data fields

Sometimes map features, such as polygons, lines, and points, contain unwanted attributes (or fields, or columns) that you may want to remove. In the Console, type the -filter-fields editing command to remove unnecessary fields.

For example, remove all fields except town:

-filter-fields town

If you want to leave more than one field, separate them by a comma, but without spaces, like that:

-filter-fields town,state

Warning: If you leave a space after comma, you will get a Command expects a single value error.

Join spreadsheet data with polygon map

Combining spreadsheet data with geographical boundaries is a common task for geospatial practitioners. Imagine you have a file with Connecticut town boundaries, and you want to add population data to each of them in order to build a choropleth map.

Mapshaper provides a powerful -join command to join such files. Remember that you need some common keys in both datasets (such as town name, or state, or country) in order to join files. Otherwise Mapshaper has no way of knowing which numbers belong to which polygons.

  1. Import both geospatial file and a CSV dataset into Mapshaper using Quick import box.
  2. Make sure both files appear in the drop-down list of layers. Your CSV data will be shown as something that resembles a table. Use the Cursor > inspect attributes tool to make sure the data is imported correctly. If you use the sample CT files, note that the ct-towns layer has name attribute with the name of the town, and ct-towns-popdensity has town names in the town column.
  3. Make your geospatial layer (ct-towns) is the one active.
  4. Open the Console, and use the -join command, like this:
-join ct-towns-popdensity keys=name,town

where ct-towns-popdensity is the CSV layer you are merging with, and keys are the attributes that contain values to join by. In case with our sample files, these would be town names which are stored in name attribute of the map file, and town column of the CSV file.

  1. You will see a message in the console notifying you if join was performed successfully, or if Mapshaper encountered any errors.
  2. Use the Cursor > inspect attributes tool to make sure you see CSV columns as fields of your polygons, like is shown in Figure 14.17.
  3. You can now save the file to your computer by clicking the Export button.
Mapshaper lets you join spatial and CSV files using common keys (for example, town names).

Figure 14.17: Mapshaper lets you join spatial and CSV files using common keys (for example, town names).

Tip: To avoid confusion, it may be useful to re-name your CSV column that contains key values to match the key attribute name of your map. In our example, you would rename town column to name column in the CSV, and your command would end with keys=name,name.

Do you remember aggregating address-level point records of hospitals into hospital counts per state discussed earlier in this chapter? Now is a good time to find that .CSV file and practice your merging skills.

Count points in polygons with Mapshaper

Mapshaper lets you count points in polygons, and record that number in polygon attributes using -join command.

  1. Import two geospatial files, one containing polygon boundaries (for example, US state boundaries), and another containing points that you want to aggregate (for example, hospitals in the US).

  2. Make sure your polygons (not points) layer is active by selecting it from the dropdown menu.

  3. In the Console, perform -join using a count() function, like this:

-join hospitals-points calc='hospitals = count()' fields=

This command tells Mapshaper to count points inside hospitals-points layer and record them as hospitals attribute of the polygons. The fields= part tells Mapshaper to not copy any fields from the points, because we are performing many-to-one matching (many hospitals per state, in our case).

  1. Use the Cursor > inspect attributes tool to make sure polygons obtained a new field with the recorded count of points, like is shown in Figure 14.18.

  2. Save the new file using Export button and choosing the desired output format. In the section below, we will talk about what happens to objects that don’t join.

Mapshaper’s -join can count points in polygons.

Figure 14.18: Mapshaper’s -join can count points in polygons.

More about joins

From the “Count points in polygons with Mapshaper” section of this chapter, you should recall that you do not need to specify keys if you want to perform join based on geographical locations between two geospatial layers (one being points, the other is polygons). If one of your files is a CSV, you need keys.

If you don’t have a CSV table that matches the columns in your boundary map data, you can easily create one. Upload the boundary map to Mapshaper, and export in CSV format. Open the downloaded file in any spreadsheet tool. To match data columns in the CSV spreadsheet, use the VLOOKUP function.

In real life, you will rarely have perfect files with one-to-one matches, so you might want to have more information about which features didn’t get matched so that you can fix your data. Mapshaper helps you keep track of data that is not properly joined or matched. For example, if the polygon map contains 169 features (one for each town in Connecticut), but the CSV table contains only 168 rows of data, Mapshaper will join all of those with matching keys, and then display this message:

[join] Joined data from 168 source records to 168 target records
[join] 1/169 target records received no data
[join] 1/169 source records could not be joined

To get more details on which values were not joined, add unjoined unmatched -info flags to your join command, like this:

-join ct-towns-popdensity keys=name,town unjoined unmatched -info

The unjoined flag saves a copy of each unjoined record from the source table into another layer named unjoined. The unmatched flag saves a copy of each unmatched record from the target table to a new layer named unmatched. And the -info flag outputs some additional information about the joining procedure to the console.

Merge selected polygons with join and dissolve commands

In Mapshaper, you can merge selected polygons into larger “clusters” using -join and -dissolve commands.

Imagine that you are employed by the CT Department of Public Health, and your task is to divide 169 towns into 20 so-called Health Districts and produce a new geospatial file. By the way, health districts are a real thing in Connecticut.

You should begin by creating a crosswalk of towns and their health districts. Computer scientists and those working with data often use the term crosswalk to describe some kind of matching between two sets of data, such as zipcodes and towns where they are located. In our case, the crosswalk can be as simple as a two-column CSV list of a town and its district, each on a new line. Because your boss didn’t give you a list of towns in a spreadsheet format, but instead a GeoJSON file with town boundaries, let’s extract a list of towns from it.

  1. Import ct-towns.geojson to Mapshaper using Quick import box.
  2. You can use the Cursor > inspect attributes tool to see that each polygon has a name attribute with the name of the town.
  3. Save attribute data as a CSV file using Export button. Open the file in any spreadsheet tool. You will see that your data is a one-column file with a *name& column that lists 169 towns.
  4. Create a second column titled merged and copy-paste values from the first, name column. At this point your spreadsheet contains two columns with the same values.
  5. Pick a few towns, for example West Hartford and Bloomfield, and assign “Bloomfield-West Hartford” to their merged column, like is shown in Figure 14.19. You may stop right here and move to the next step, or keep assigning district names to a few other neighboring towns.
Create a two-column crosswalk of towns and which districts they should be merged to.

Figure 14.19: Create a two-column crosswalk of towns and which districts they should be merged to.

  1. Save this new file as ct-towns-merged.csv, and drag-and-drop it to Mapshaper on top of your ct-towns layer. Click Import.
  2. This new CSV layer will be added as ct-towns-merged and will appear as a series of table cells. From the dropdown menu, select ct-towns to get back to your map.
  3. Now you are ready to merge certain towns into districts according to your uploaded CSV file. Open the Console, and type:
-join ct-towns-merged keys=name,name

to join the CSV layer with the boundaries layer that you see on the screen, followed by

-dissolve merged

to dissolve polygons of towns according to the merged column of the CSV file.

In our example, only Bloomfield and West Hartford are dissolved into a combined “Bloomfield-West Hartford” regional health district (with the shared boundary between towns becoming grayed out), and all of the other polygons remain the same. Figure 14.20 shows the final result.

Merge polygons based on a predefined crosswalk.

Figure 14.20: Merge polygons based on a predefined crosswalk.

You can inspect attribute data of polygons using Cursor > inspect attributes tool, and save the resulting file using the Export button.

Learn more advanced MapShaper methods

There are many more commands within Mapshaper that are worth exploring if you are serious about GIS, such as changing projections, filtering features using JavaScript expressions, assigning colors to polygons based on values, and many more. Explore the Wiki of Mapshaper project on GitHub for more commands and examples.