Skip to content

oex

oex (Open Data Exporter) exports country-scale vector data from OpenStreetMap and Overture Maps to GeoPackage, Shapefile, GeoJSON, or KML, with optional HDX publication.

Install

curl -LsSf https://raw.githubusercontent.com/osgeonepal/oex/main/scripts/install.sh | sh

That installs the oex-cli command using the first of uv, pipx, conda, pip --user or docker it finds on your machine. Other paths:

uv tool install oex
pipx install oex
pip install --user oex

Or run the docker image directly:

docker run --rm -v "$PWD/output:/app/output" \
  ghcr.io/osgeonepal/oex:latest oex-cli osm npl

When docker is the only installer found, the one-line installer writes /usr/local/bin/oex-cli wrapping the docker image.

Usage

# Download a country with the bundled defaults
oex-cli osm npl

# Use a curated category set from the source repo (HOT-style, Overture package, ...)
oex-cli osm --config configs/examples/hot-schema.yaml --iso3 NPL

# Define your own categories
oex-cli osm --config ./my-stuff.yaml

Replace npl with any ISO3. Switch osm for overture to pull from Overture Maps instead.

Outputs land in ./output/<iso3>/<source>/<key>_<iso3>_<category>_<format>.zip. Each zip contains the GIS file(s), README.txt, config.yaml, and optionally metadata.json (when output.metadata or output.report.enabled is on), which is the layer as a STAC Item carrying per-column null shares, distinct counts, geometry types and bbox.

Export contents

  • 8 default categories: Buildings, Roads, Hospitals, Schools, Rivers, Land Use, Transportation Hubs, Settlements.
  • 12-layer HOT-style HDX schema mirroring hotosm_<iso3>_* exports.
  • 15-dataset Overture data package (one per theme/feature_type).
  • Output formats: gpkg, shp, geojson, kml, fgb, geoparquet. Default is [gpkg, shp].
  • Four OSM engines: a per-country PBF on demand (Geofabrik), a planet PBF cache for batch runs across many countries, and two that query a live OSM database (Postpass, HOT Raw Data API) for event response.
  • Administrative pcode tagging: each feature gets pcode and name columns for the admin levels its country has, up to adm4, from fieldmaps.io humanitarian boundaries (opt-in, enabled by default in the HOT schema).

Stack

Concern Tool
Query engine DuckDB + spatial extension
OSM parser QuackOSM
Overture access DuckDB httpfs over s3://overturemaps-us-west-2
Boundaries (default) geoBoundaries gbOpen ADM0
Package manager uv
Linter / type-check ruff / ty

Documentation