imclab/shapefile

A streaming parser for the ESRI Shapefile spatial data format.

Streaming Shapefile Parser

Based on the ESRI Shapefile Technical Description and dBASE Table File Format.

Caveat emptor: this library is a work in progress and does not currently support all shapefile geometry types (see shp.js for details). It also only supports dBASE III and has no error checking. Please contribute if you want to help!

Reading a Shapefile

# shapefile.read(filename[, options], callback)

A convenience API for reading an entire shapefile in one go. Use this method if you don’t mind putting the whole shapefile in memory; use reader instead if you want to process records individually. The specified callback with two arguments:

• error - the error, if any
• collection - a GeoJSON feature collection

The collection has a bbox property containing representing the bounding box of all records in this shapefile. The bounding box is specified as [xmin, ymin, xmax, ymax], where x and y represent longitude and latitude in spherical coordinates.

Streaming a Shapefile

# shapefile.reader(filename[, options])

The main API for reading a shapefile. The supported options are:

• encoding - the DBF encoding (defaults to ISO-8859-1)
• ignore-properties - if true, don’t read properties (faster; defaults to false)

This method returns a reader object.

# reader.readHeader(callback)

Reads the shapefile header, invoking the specified callback with two arguments:

• error - the error, if any
• header - the header object

The header object is simply an object with a bbox property representing the bounding box of all records in this shapefile. The bounding box is specified as [xmin, ymin, xmax, ymax], where x and y represent longitude and latitude in spherical coordinates.

# reader.readRecord(callback)

Reads the next shapefile record, invoking the specified callback with two arguments:

• error - the error, if any
• record - the record object, or shapefile.end

The record object is a GeoJSON feature. (GeoJSON objects are the standard representation of geometry in JavaScript, and they are convenient. If you want to access the shapefile primitives directly, use the private shp and dbf classes instead.)

If there are no more records in this shapefile, the record is the special value shapefile.end.

# reader.close(callback)

Closes the underlying files for this reader. You should call this when you are done reading. If an error occurs during readHeader or readRecord, the reader will be closed automatically.

# shapefile.end

A sentinel value used readRecord to indicate that the end of the file has been reached, and no more records are available. (Note that if the end of file is reached when readHeader is called, this is considered an error because the header is required by the shapefile format.)