Skip to content

Get started

Install

Pick one. All install the oex-cli command.

One-line installer

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

It uses the first installer it finds on your machine: uv, then pipx, then conda, then pip --user. When only docker is found, it writes a docker wrapper at /usr/local/bin/oex-cli. If the install succeeds but oex-cli is not on your PATH, the installer says so, prints how to add it, and exits with an error.

uv

uv tool install oex
oex-cli osm npl

pipx

pipx install oex
oex-cli osm npl

pip

pip install --user oex
oex-cli osm npl

Docker, no install

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

For the short form, set a shell alias once:

alias oex-cli='docker run --rm \
  -v "$PWD/output:/app/output" \
  -v "$PWD/configs:/app/configs:ro" \
  ghcr.io/osgeonepal/oex:latest oex-cli'

After that, oex-cli osm npl runs the container.

Usage

Download a country

oex-cli osm npl

Eight bundled categories (Buildings, Roads, Hospitals, Schools, Rivers, Land Use, Transportation Hubs, Settlements) for Nepal as GeoPackage and Shapefile zips.

Replace npl with any ISO3: usa, bra, ind, ken, ngr, ...

For Overture Maps instead of OSM:

oex-cli overture npl

Use a curated category set

Example schemas live in configs/examples/ in the source repository, and in the docker image at /app/configs/examples/. They are not installed by pip or uv tool install, so from a released package download the one you want and pass its path to --config. From a source checkout:

# HOT-style HDX layers (12 categories matching hotosm_<iso3>_*)
oex-cli osm --config configs/examples/hot-schema.yaml --iso3 NPL

# Full Overture data package (15 datasets, one per theme/feature_type)
oex-cli overture --config configs/examples/overture-package-schema.yaml --iso3 NPL

# Minimal custom example (Hospitals + Healthcare POIs)
oex-cli osm --config configs/examples/custom-schema.yaml --iso3 NPL

These are starting points to copy and edit, not a supported interface: their category lists and HDX metadata change between releases.

Add your own category

Write a YAML:

# my-stuff.yaml
iso3: NPL
key: my_stuff
dataset_name: Nepal Coffee Shops
categories:
  - name: Cafes
    osm:
      filter:
        amenity: ["cafe"]
      select:
        - feature_id AS id
        - tags['name'] AS name
        - tags['opening_hours'] AS opening_hours

Run it:

oex-cli osm --config ./my-stuff.yaml

See Custom categories for the full schema reference.

Output location

output/
└── npl/
    ├── osm/
    │   ├── my_stuff_npl_buildings_gpkg.zip
    │   └── my_stuff_npl_buildings_shp.zip
    └── overture/
        └── ...

Each zip contains the GIS file(s) plus 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.

OSM engine: geofabrik vs planet

Two engines feed the OSM exporter. The right one depends on how you want country PBFs to land on disk.

  • engine: geofabrik (default). Downloads the per-country PBF from Geofabrik's mirror (~30 to 200 MB depending on country). One run per country pays a small download. The snapshot date is the date Geofabrik last rebuilt the extract.

  • engine: planet. Clips the country PBF out of a local planet PBF (~87 GB) using osmium extract --strategy=complete_ways, then runs quackosm once with the union of all category tag filters. Picks every feature the schema cares about in a single PBF parse, no per-category reparse. Useful when you control the snapshot date or are sweeping many countries from one local planet.

Requires osmium-tool on PATH:

# Fedora / RHEL
sudo dnf install osmium-tool

# Debian / Ubuntu
sudo apt install osmium-tool

# macOS
brew install osmium-tool

And a planet PBF locally; download once with:

oex-cli osm-build-cache

Point your config at it:

source:
  osm:
    engine: planet
    pbf_path: /path/to/planet-latest.osm.pbf

Or, to prefer geofabrik but fall back to planet for countries Geofabrik doesn't publish (e.g. some small territories):

source:
  osm:
    engine: geofabrik
    planet_fallback: true
    pbf_path: /path/to/planet-latest.osm.pbf

By default a missing pbf_path is a loud failure. To download the planet PBF when it is missing, and again whenever pbf_url serves a newer one (with snapshot: latest), opt in:

source:
  osm:
    auto_download_planet: true

or pass --download-if-missing on the CLI.

Develop from source

git clone https://github.com/osgeonepal/oex
cd oex
just setup
just test
just run osm nepal