Looking for V2 documentation? Click here9.
ogr2ogr wraps the
ogr2ogr
GDAL tool to enable file conversion and re-projection of spatial data in simplified friendly API.Installation
- Install GDAL tools1 (includes the
ogr2ogr
command line tool)
- Install package:
npm install ogr2ogr
Usage
ogr2ogr takes either a path, a stream, or a GeoJSON2 object. The result of the transformation will depend on the format returned.// Using CommonJS modules
const ogr2ogr = require('ogr2ogr').default
// Using ECMAScript modules or Typescript
import ogr2ogr from 'ogr2ogr'
// Promise API
(async() {
// Convert path to GeoJSON.
let {data} = await ogr2ogr('/path/to/spatial/file')
console.log(data)
// Convert GeoJSON object to ESRI Shapefile stream.
let {stream} = await ogr2ogr(data, {format: 'ESRI Shapefile'})
// Convert ESRI Shapefile stream to KML text.
let {text} = await ogr2ogr(stream, {format: 'KML'})
console.log(text)
})()
// Callback API
ogr2ogr('/path/to/spatial/file').exec((err, {data}) => {
console.log(data)
})
Formats
ogr2ogr has varying support for format input and output. Consult the particular driver3 you are interested in for more details. It is highly recommend to run the latest version of GDAL to get the best support. This project attempts to cast the widest net for support. Here are some notables:| Drivers | Output | Notes | | ----------------------------------------------------- | -------- | ------------------------------------------- | | GeoJSON |
data
| Default format returned when none specified |
| CSV, GeoRSS, GML, GMT, GPX, JML, KML, MapML, PDF, VDV | text
| Drivers supporting /vsidout/
return text |
| Other | stream
| All other drivers return a file stream |API
ogr2ogr(input, options?) -> Promise\
Theinput
may be one of:- A path (
string
). This includes file paths and network paths including HTTP endpoints. - A
ReadableStream
. - A GeoJSON2 object.
The following
options
are available (none required):format
- Output format (default:GeoJSON
)timeout
- Timeout, in milliseconds, before command forcibly terminated (default:0
)maxBuffer
- Max output size in bytes for stdout/stderr (default:1024 * 1024 * 50
)options
- Custom ogr2ogr arguments4 and driver options5 (e.g.['--config', 'SHAPE_RESTORE_SHX', 'TRUE']
)env
- Custom environmental variables (e.g.{ATTRIBUTES_SKIP: 'YES'}
)destination
- Select another output than the output object (e.g. useful for writing to databases).command
- Command to run (default:ogr2ogr
)
The
output
object has the following properties:cmd
- Theogr2ogr
command executed (useful for debugging).text
- Text output from drivers3 that support/vsistdout/
(see formats above)data
- Parsed GeoJSON2 output (used whenformat
isGeoJSON
)stream
- AReadableStream
of the output. Used for drivers3 that do not support/vsistdout/
.
ESRI Shapefile
), this will be a zip stream containing all the data.extname
- The file extension of the data returned.details
- Any text printed toSTDERR
. This includes any warnings reported by ogr2ogr when it ran.
ogr2ogr(input, options?).exec((err, output))
The callback API supports the same options as above but in a NodeJS style callback format.Tips and tricks
Runningogr2ogr
in a Docker container6:ogr2ogr("/home/.../path/to/spatial/file", {
command: "docker run -v /home/:/home --rm osgeo/gdal ogr2ogr",
})
Converting an isolated
.shp
file:ogr2ogr("/path/to/file.shp", {
options: ["--config", "SHAPE_RESTORE_SHX", "TRUE"],
})
Getting more debug information by using the
CPL_DEBUG
7 option. Debug info added to details
on the output
object.ogr2ogr("/path/to/file.shp", {
options: ["--config", "CPL_DEBUG", "TRUE"],
})
Parsing custom geometry fields in a CSV. Use CSV driver options8, like:
ogr2ogr("/path/to/file.csv", {
options: ["-oo", "GEOM_POSSIBLE_NAMES=the_geom"],
})
Re-project geometry:
ogr2ogr("/path/to/file.shp", {
options: ["-t_srs", "EPSG:4326"],
})