Shapefile
ESRI Shapefiles is a file format for storing geospatial vector data.
@loaders.gl/shapefile
- Wikipedia - ESRI Shapefile Whitepaper - Notes on Shapefile usage
- DBF header - data types - code pages - implementation notes
Note that Shapefiles are falling out of favor in modern usage (likely due to the significant inconvenience of having to deal with multiple files). However, a lot of valuable geospatial data available is still provided in Shapefile format, and sometimes only in this format. Additional information and some strong opinions can be found at switchfromshapefile.org.
A multi-file format
A Shapefile consists of a number of files that must be read and written together.
Because of this, they are typically stored together with the same file name but different extensions.
These related files are usually stored in the same directory or inside a common zip archive.
While it is possible to just load the geometries from a .shp
file, files with extensions .shp
, .shx
, .dbf
are often expected to exist,
and additional files with other extensions such as .prj
and .cpg
may also exist, if needed.
A common problem with shapefiles is that the user only opens the .shp
file but not the accompanying files such as .dbf
.
File | Type | Contents |
---|---|---|
.shp | Binary | The geometry, i.e. the geometry column in the resulting table. |
.dbf | Binary | The attributes, i.e. the data columns in the resulting table. |
.shx | Binary | The index (technically required, however it is sometimes possible to open shapefiles without the index) |
.prj | Text | A small usually single line text file containing a WKT-CRS style projection. WGS84 is assumed if not present. |
.cpg | Text | A small text file containing a text encoding name for the DBF text fields. latin1 is assumed if not present. |
Coordinate Systems
Arbitrary coordinate reference systems are supported for Shapefiles.
Such coordinate systems are reprojected to WGS84 on import.
Encodings
The optional "code page" file (.cpg
) specifies the encoding of any text data in the Shapefile (or more precisely, in the sidecar .dbf
file). If no .cpg
file is provided, latin1
encoding is assumed.
Geometries
A Shapefile always encodes a single type of geometries. The following geometries are supported:
Shape type | GeoJSON | loaders.gl | Value | Fields |
---|---|---|---|---|
Null shape | null | ✅ | 0 | None |
Point | Point | ✅ | 1 | X, Y |
Polyline | LineString | ✅ | 3 | MBR, Number of parts, Number of points, Parts, Points |
Polygon | Polygon | ✅ | 5 | MBR, Number of parts, Number of points, Parts, Points |
MultiPoint | MultiPoint | ✅ | 8 | MBR, Number of points, Points |
PointZ | Point | ✅ | 11 | X, Y, Z Optional: M |
PolylineZ | LineString | ✅ | 13 | MBR, Number of parts, Number of points, Parts, Points, Z range, Z array Optional: M range, M array |
PolygonZ | Polygon | ✅ | 15 | MBR, Number of parts, Number of points, Parts, Points, Z range, Z array Optional: M range, M array |
MultiPointZ | MultiPoint | ✅ | 18 | MBR, Number of points, Points, Z range, Z array Optional: M range, M array |
PointM | Point | ✅ | 21 | X, Y, M |
PolylineM | LineString | ✅ | 23 | MBR, Number of parts, Number of points, Parts, Points Optional: M range, M array |
PolygonM | Polygon | ✅ | 25 | MBR, Number of parts, Number of points, Parts, Points Optional: M range, M array |
MultiPointM | MultiPoint | ✅ | 28 | MBR, Number of points, Points Optional Fields: M range, M array |
MultiPatch | ❌ | 31 | MBR , Number of parts, Number of points, Parts, Part types, Points, Z range, Z array Optional: M range, M array |
value
is the internal shapefile encoding
Version History
- The shapefile format was introduced with ArcView GIS version 2 in the early 1990s.
Troubleshooting
- No data columns: The most common problem with shapefile is probably that they user only opens the main
.shp
file. In this case only the geometry is included, but no data columns are present. - Geometry projection issues: geometry may fail to load or be visualized incorrectly without the associated
.prj
file. - Incorrect strings: Encodings may not be correct without the
.cpg
file.
Also note that there is a very large number of possible projections and it is hard to test that every possible projection is supported. If your data is old or known to be problematic, it may be worth double checking that things look correct after importing.