Getting started

routing-earth-utils version

Read this online at docs.routing-earth.com.

routing-earth-utils (CLI is re) is the client software to initialize a local Valhalla graph extract and to consume daily/weekly graph delta updates with up-to-date OSM road data.

Requirements

  • Python ≥ 3.12 (binary wheels for Linux x86_64/aarch64, macOS arm64, Windows amd64)
  • A paid routing-earth.com API key with an entitlement for your scope & cadence (get one at routing.earth)
  • Disk: syncing briefly holds two copies of the extract plus the downloaded bundles (~2× the extract size)

Install

=== "uv"

```sh
uv tool install routing-earth-utils
# or, inside a project:
uv add routing-earth-utils
```

=== "pip"

```sh
pip install routing-earth-utils
```

This installs the re command.

Authentication

The CLI reads your API key from the environment (or pass --api-key):

export RE_API_KEY="re_..."

The key is only ever sent as a Bearer header to the routing.earth API. 401 means the key is invalid, 403 means it has no entitlement for the requested scope & cadence.

re init - Seed the extract

Pick a scope (planet or a region id, e.g. germany) and a cadence (daily, weekly or monthly) matching your plan, then:

re init --tar-extract tiles.tar --scope germany --cadence daily

This downloads the current full snapshot, verifies its signature, and writes a ready-to-serve extract:

initialized tiles.tar at dataset_id 20260718 (germany/daily)

Serve it

Point Valhalla at the tar in your valhalla.json:

{
  "mjolnir": {
    "tile_extract": "/path/to/tiles.tar"
  }
}

re sync - Keep it current

re sync --tar-extract tiles.tar

This downloads the diff bundle chain, applies it tile by tile, and atomically swaps the new extract into place. If your extract is too far behind, we might decide to pull a fresh full graph.

Every step along the chain is verified via our bundle signatures (Ed25519), and a per-tile checksum check adds additional security. Any failure aborts the sync and leaves your current extract untouched.

Operationally, run re sync on a scheduler with e.g. a 15 mins cadence:

# e.g. crontab, for a daily cadence
*/15 * * * * RE_API_KEY=re_... re sync --tar-extract /srv/valhalla/tiles.tar

Exits with code:

  • 0 on success (including "already current")
  • 1 on any failure

!!! note "Picking up the new extract" The swap is an atomic rename. A running Valhalla keeps serving the old extract from its memory map until it reopens the file — restart or reload the service after a successful sync to serve the new data.

re status - Check local graph's update status

re status --tar-extract tiles.tar

{"tar_extract": "tiles.tar", "dataset_id": 20260718, "scope": "germany", "cadence": "daily", "verdict": "diff-chain", "latest_dataset_id": 20260719, "osm_data_timestamp": "2026-07-19T02:00:00Z"}

Add --offline to simply print the local graph status without requesting our API.

Exits with code:

  • 0 on verdict = current
  • 1 on error
  • 2 on verdict = diff-chain, i.e. graph needs an update

Using the Python API

Everything the CLI does is available as a library — see the API reference, starting with client:

from pathlib import Path
from routing_earth_utils.client import init, sync, tar_status

extract = Path("tiles.tar")
if not extract.exists():
    init(extract, scope="germany", cadence="daily")
result = sync(extract)
print(result.verdict, result.to_dataset_id)

Troubleshooting

Symptom Cause / fix
resolver: HTTP 401 (invalid API key) $RE_API_KEY unset or wrong — check the export and your account.
resolver: HTTP 403 (no entitlement for this scope/cadence) Your plan doesn't cover this scope × cadence — re-check init arguments against your subscription.
not an initialized extract The tar wasn't created by re init (or is some other file). Seed it with init first.
already exists — use sync init never overwrites; advance an existing extract with sync, or remove it to reseed.
Signature / verification errors Fail-closed by design: the download was rejected and your extract is untouched. The <extract>.work dir is kept for diagnosis (safe to delete; the next run starts clean). Retry; if it persists, contact support.
Sync fails with a disk-space error Copy-on-sync needs roughly the extract's size in free space next to it.

Increase verbosity with -v (progress) or -vv (debug); diagnostics go to stderr.

Project links

Data verified by PyPI on Aug 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nilsnolde from gravatar.com nilsnolde

Credits

Author: Nils Nolde

GitHub Statistics

Data verified by PyPI on Aug 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

LicenseRef-Proprietary
View SPDX License List

Requires

Python >=3.12

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

routing_earth_utils-0.2.2-cp312-abi3-win_amd64.whl (347.6 kB view details)

Uploaded CPython 3.12+Windows x86-64

routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (197.0 kB view details)

Uploaded CPython 3.12+manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (183.3 kB view details)

Uploaded CPython 3.12+manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

routing_earth_utils-0.2.2-cp312-abi3-macosx_11_0_arm64.whl (106.4 kB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

File details

Details for the file routing_earth_utils-0.2.2-cp312-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for routing_earth_utils-0.2.2-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 292a0b17332d77d428e5bca6496cb554d1cb5878952d91adf9575ece31fd1764
MD5 faeb1a9597bc8543eb381f321ca3241d
BLAKE2b-256 382d0f20af50ee297971cde4b8cd7db279189a14f898afe138eee35cdf171816

See more details on using hashes here.

Provenance

The following attestation bundles were made for routing_earth_utils-0.2.2-cp312-abi3-win_amd64.whl:

Publisher: wheels.yml on routing-earth/routing-earth-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0cba6fb99e504bbc4534058ce0c07ebb2033e686bcc8b5f49f92d936beecccb0
MD5 3a8e827d0cf8e732dc8be31c82096713
BLAKE2b-256 accc205217cf61c6afaf595484886e6fb32bf455a392914f4bc37bfacaa792a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on routing-earth/routing-earth-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 a715350e00a1697ba90cb1e92d8358908917d35005f56e30bcd555f6f583472a
MD5 830a99e65319a98ec5bc382e47f8ad10
BLAKE2b-256 3bdc60bb177eb935470e32689105c79e33e1041e5e67f2f09c1b2580f9eba669

See more details on using hashes here.

Provenance

The following attestation bundles were made for routing_earth_utils-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl:

Publisher: wheels.yml on routing-earth/routing-earth-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file routing_earth_utils-0.2.2-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for routing_earth_utils-0.2.2-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 404cee00eb236130513028f115e9025d45835176344993db9ef5bb1b94c7f1a0
MD5 676f3d341f352db3bb4f8b47bad34254
BLAKE2b-256 71ca7b23f08a05bfb50d9b921c04912ec93bc4b78e88effa8eb175cf03b4f289

See more details on using hashes here.

Provenance

The following attestation bundles were made for routing_earth_utils-0.2.2-cp312-abi3-macosx_11_0_arm64.whl:

Publisher: wheels.yml on routing-earth/routing-earth-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.2 This release

4 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page