Some useful commands, with examples

Get help using mapshaper

                
                    #List all the available commands
                    mapshaper -h

                    #See detailed options for the simplify command
                    mapshaper -h simplify
                
            

Get information about a dataset

                
                    # Summarize a dataset and list attribute fields
                    mapshaper mystery_data.json -info

                    #Calculate some statistics about attribute data (INCOME is a field name)
                    mapshaper provinces.shp -calc 'min(INCOME)' -calc 'median(INCOME)' -calc 'max(INCOME)'
                
            

Convert between file formats

• mapshaper *.shp -o format=geojson # Convert all the Shapefiles in a directory into GeoJSON.
• mapshaper locations.csv -points x=lng y=lat -o format=geojson# Convert a CSV file with lat/lng fields to a GeoJSON file containing point features.

Simplify a polygon layer (works for polylines too)

• mapshaper counties.shp -simplify 10% -o out.shp# Retain 10% of removable vertices

Clip a layer of polygons, lines or points using polygons in a second layer

• mapshaper states.shp -clip land_area.shp -o clipped.shp

Erase parts of a polygon, line or point layer using a second polygon layer

• mapshaper land_areas.shp -erase water_bodies.shp -o erased.shp

Aggregate polygons by dissolving edges

                
                    # Dissolve polygons in a feature layer into a single polygon
                    mapshaper states.shp -dissolve -o country.shp
                    
                
            

• mapshaper counties.shp -dissolve STATE_FIPS copy-fields=STATE_NAME sum-fields=POPULATION -o states.shp # Generate state-level polygons by dissolving a layer of counties
  # (STATE_FIPS, POPULATION and STATE_NAME are attribute field names)

Join an external data table to a feature layer

                
                    # Join a csv table to a Shapefile
                    # Tip: the FIPS:str type definition prevents the values in the FIPS field from being converted to numbers
                    mapshaper states.shp -join demographics.csv keys=STATE_FIPS,FIPS field-types=FIPS:str -o joined.shp

                    # Join the dbf table from one Shapefile to another Shapefile
                    mapshaper states.shp -join states2.dbf keys=STATE,STATE -o joined.shp
                
            

Use an attribute as an id

                
                    # Add data field to use as identifier
                    mapshaper -i counties.shp -o counties.svg id-field=gID format=svg
                
            

Edit the attribute table

                
                    # Add data fields using a JavaScript expression
                    mapshaper counties.shp -each "STATE_FIPS=CNTY_FIPS.substr(0, 2), AREA=$.area"
                
            

Use a sequence of commands

                
                    # List all the available commands
                    mapshaper -h

                    #See detailed options for the simplify command
                    mapshaper -h simplify
                
            

Most of mapshaper's commands apply to layers of data features. A layer is a collection of features with the same geometry type and a consistent set of data properties (or no data properties). Mapshaper supports polygon, polyline and point layers. For all of these types, a single feature may contain one geometric shape, multiple shapes, or no shapes (i.e. null/empty geometry).

The simplest way to use mapshaper is to import a single layer of features, edit it, and save to a file

Version 0.2.0 introduced support for multiple layers along with new syntax for selecting which layer or layers a command should target. The -target command takes a (comma-separated) list of one or more layers for the subsequent command to target. As an alternative, most commands support the target= option.

The following example shows how to import a layer of province boundaries, create a second layer consisting of just the shared boundaries, simplify the geometry and save both layers as GeoJSON files. In this example, the -innerlines command is invoked with two options: +, which creates a new layer instead of replacing the target layer, and name=lines, which renames the new layer. The output is two files,out/provinces .json and out/lines.json .

                mapshaper provinces.shp \

                    -simplify 20% \

                    -innerlines + name=lines \

                    -target provinces,lines \

                    -o format=geojson out/
                
            

When importing TopoJSON files, mapshaper treats each named object as a separate layer. The next example shows how to import a TopoJSON file containing a layer named states along with several other layers, extract the feature for Hawaii and save it as a GeoJSON file. In this example, invoking -filter with target=states applies the filter command to the layer named states . The subsequent -o command targets the output of the previous command.

                mapshaper usa.topojson \

                    -filter 'STATE == "HI"' target=states \

                    -o out/hawaii.json format=geojson