overpass-go

overpass-go is a Go implementation of the Overpass API query execution engine. It provides a library and command-line tools for OpenStreetMap data.

Install

Download an archive from GitHub Releases. Each platform archive contains overpass, overpass-server, and overpass-diff. Linux and macOS use .tar.gz; Windows uses .zip. Builds are available for amd64 and arm64. Extract the archive, verify it against checksums.txt, and put the commands on your PATH. No Go installation is required. Run overpass-diff from the extracted directory or set -manifest to the included cmd/overpass-diff/nz-manifest.json file.

To install from source with Go (see go.mod for the required version):

go install github.com/ebuckley/overpass-go/cmd/overpass@main
go install github.com/ebuckley/overpass-go/cmd/overpass-server@main
go install github.com/ebuckley/overpass-go/cmd/overpass-diff@main

Use a release tag instead of main to pin a version. After the first stable release, @latest selects the latest stable version.

Library

go get github.com/ebuckley/overpass-go@main

Import github.com/ebuckley/overpass-go/engine for RunQL, RunXML, PrepareQL, and PrepareXML. The store package provides the storage interfaces, and store/boltstore provides persistent storage. The root of the module has no Go package; import the package you need.

The library and commands use the same AGPL-3.0-or-later license.

Quick start

# Load a PBF extract into a bbolt database.
go run ./cmd/overpass -data nz.osm.pbf -index nz.osm.pbf.db -v

# Start the local interpreter service.
go run ./cmd/overpass-server -data nz.osm.pbf.db

# Send an Overpass QL query.
curl -X POST \
  -d '[out:json][timeout:25];way(around:1000,-43.5320,172.6362)[highway];out geom;' \
  http://localhost:8080/api/interpreter

Overpy acceptance

This manual acceptance check uses only the local server. It does not run from Go tests. Build a database from the checked-in interpreter fixture, start the server in a separate terminal, then run the pinned client:

go run ./cmd/overpass -data interpreter/testdata/small.osm -index /tmp/overpy-small.db
go run ./cmd/overpass-server -data /tmp/overpy-small.db -listen 127.0.0.1:8080

python3 -m venv /tmp/overpy-acceptance-venv
/tmp/overpy-acceptance-venv/bin/python -m pip install -r acceptance/overpy/requirements.txt
/tmp/overpy-acceptance-venv/bin/python acceptance/overpy/run.py

The final command sends JSON and XML queries to http://127.0.0.1:8080/api/interpreter. Use --url to select another local server address. Dependency installation can use a package cache or other local package source; the runner contacts only the server URL.

Live differential

Run the local server with the frozen database before this command. The command contacts the public service only when you run it. It checks the PBF identity before it sends semantic queries and saves artifacts for failures and known absences.

# Use the frozen PBF that is named in the manifest.
go run ./cmd/overpass-diff \
  -data nz.osm.pbf \
  -local-url http://127.0.0.1:8080/api/interpreter \
  -public-url https://overpass-api.de/api/interpreter

Continuous integration

Run the complete local CI gate with one command:

./ci.sh

The script builds, vets, lints, and tests all packages. It runs the pinned golangci-lint v2.13.2 suite for duplication, function length, and maintainability. Go downloads the pinned linter on the first run. The script measures repository-wide statement coverage and requires at least 85%. Successful steps produce one summary line. A failed step prints the end of its log. Complete logs and the coverage profile are in .ci/.

Use CI_COVERAGE_MIN only to test a proposed coverage threshold. Do not lower the normal gate to make a change pass.

GitHub Actions calls this same script on pull requests, pushes to main, and version tag pushes. It saves .ci/ logs even when a check fails. After CI passes, it builds all release platforms, including on pull requests.

Releases

Each successful push or merge to main creates a tag and GitHub prerelease named v0.0.0-main.<commit-timestamp>.<run-number>. These builds do not replace the latest stable release. To publish a stable release, push a version tag:

git tag -a v0.1.0 -m 'Release v0.1.0'
git push origin v0.1.0

Tag the intended commit only after its changes are ready to release. Tags must use vMAJOR.MINOR.PATCH, with an optional prerelease suffix. Keep major versions below v2 until the module path is updated for Go's major-version rules. A tag with a suffix publishes a prerelease.

Publishing runs only for pushes in ebuckley/overpass-go, after CI and all builds pass. It uses the built-in GitHub token with contents: write in the publish job. No personal access token is needed. Reruns leave existing releases unchanged. A manual workflow run builds artifacts without publishing.

To build the same archives locally without publishing:

bash scripts/release.sh v0.1.0

This requires Bash, Go, Git, tar, and zip, plus sha256sum or shasum. The output directory (dist/v0.1.0 by default, or the second argument) must not exist. Local builds include non-ignored working-tree changes. Each release includes SHA-256 checksums, license notices, and a source archive with vendored Go dependencies and the build scripts. The binaries use CGO_ENABLED=0.

License and attribution

Copyright 2026 overpass-go contributors. Licensed under the GNU Affero General Public License, version 3 or later (AGPL-3.0-or-later).

This project is a Go rewrite based on the original Overpass API, by Roland Olbricht and contributors. See NOTICE for attribution. This is an independent project, not an official release of the original Overpass API.