From OpenStreetMap Wiki
(Redirected from GDAL)
Jump to navigation Jump to search

The OGR Simple Features Library is a C++ Open Source library (and commandline tools) providing read (and sometimes write) access to a variety of GIS databases and vector file formats. It is related to GDAL, which focuses on raster formats.

The GDAL/OGR library itself has a OGR OSM driver that supports reading OSM XML and PBF files (starting with GDAL 1.10)

The library comes with utilities to convert and query datasets. The general idea is that

  • each supported file format is called a driver (see here the list of drivers and the docs of each driver)
  • you do command source destination where source may be a file, URL, a file inside a zip, ... (see docs)


ogr2ogr is a utility that comes with the library that can read OSM data and write formats supported by OGR.

Example conversions:

  • Minimal example: ogr2ogr -f "ESRI Shapefile" outputdir inputosm.osm
  • Error handling: ogr2ogr --config OSM_USE_CUSTOM_INDEXING NO -skipfailures -f "ESRI Shapefile" output input.osm -overwrite
  • Another example: ogr2ogr -overwrite --config OSM_CONFIG_FILE my_osmconf.ini -skipfailures -f "ESRI Shapefile" charentilly charentilly.osm

ogr2ogr schema

For the feature identifiers, ogr2ogr creates these columns:

  • ogc_fid with an auto-generated number
  • osm_id, if so instructed in osmconf.ini

OSM tags are stored as plain text strings in JSON format ('{"key":"value"}') or HSTORE format ('"key"=>"value"'), depending on osmconf.ini. The column name is all_tags or other_tags, depending on osmconf.ini.

Compatibility with old versions:

  • GDAL's SQL driver can write JSON since GDAL 3.7.[1] Before that version, ogr2ogr can only produce HSTORE.
  • GDAL < 3.9.0 produces wrong (unparseable) JSON, that SQLite will refuse to work with, if the OSM tags contain special characters. For example, a literal newline character in inscription=*. This is fixed in GDAL >= 3.9.0.[2]


ogrinfo is a utility that comes with the library that can query datasets supported by OGR.

Example queries:

  • ogrinfo -sql applies a SQL query to a database-backed file format (SQLite, GeoPackage). For examples, search for -sql in the GeoPackage and the SQLite driver docs.
    • SQL can do cool things. To join datasets: ogrinfo dataset_1 -sql "SELECT ... JOIN ..." -oo PRELUDE_STATEMENTS="ATTACH DATABASE 'dataset_2' AS other_schema" (sources: the GeoPackage and the SQLite driver docs)
  • ogrinfo -where can search for an OpenStreetMap tag: for example ogrinfo -ro source.geojson OGRGeoJSON -where "name=Warsaw" (source: GeoJSON driver's docs)

Bundling tools

Being a low-level lightweight C++ tool, ogr2ogr converting functions tends to get bundled into other tools, which wrap the functionality in different interfaces. Some of these pre-date the adding of OSM support, and so they used to provide the only interface from OSM data into these other formats (But OSM support has since been included in OGR itself)

  • Osmium - has support for OGR geometries and can be used to build converters from OSM to various GIS databases and file formats.
  • GeoConverter - is an online tool offering some of these conversions
  • QGIS - The desktop GIS software QGIS uses GDAL/OGR too to support many formats. It also provides the GdalTools Plugin, which integrates gdal-tools into QGIS for processing raster data.
  1. From the release notes: OSM driver: add a tags_format=json osmconf.ini setting and TAGS_FORMAT=JSON open option, as an alternative for HSTORE for other_tags/all_tags fields (#7533)
  2. From the 3.9.0 release notes: properly escape special characters with TAGS_FORMAT=JSON open option.