Quickstart

Build a Pack for Ontario, Canada, serve it, and send it your first forward and reverse queries. Any other region in the catalog works the same way.

1. Install og

Install og from source with Cargo.

cargo install --git https://github.com/open-geocode-rs/open-geocode --features tui

This installs two binaries:

og builds and serves Packs, and opens the interactive interface.
open-geocode runs batch CSV geocoding, benchmarks and lower-level Pack tools.

To check that og was installed, run:

og --version

og 0.x.y

2. Build a Pack

Build a Pack for Ontario with og build.

og build --region canada/ontario

og downloads Ontario’s OpenStreetMap extract, then builds a Pack from it. It prints one line per step as it goes, and a Pack ready line with the Pack’s path, record count and size when it is done.

3. Serve it

Serve the Pack with og serve.

og serve canada-ontario

Serving <og home>/packs/canada-ontario at http://127.0.0.1:8080

The API is now listening on http://127.0.0.1:8080.

4. Query it

Forward geocode a free-form address with /search.

curl 'http://127.0.0.1:8080/search?q=10+King+Street+Toronto'

Reverse geocode a point with /reverse. Longitude comes first, as in GeoJSON.

curl 'http://127.0.0.1:8080/reverse?lon=-79.38&lat=43.65'

Both return a GeoJSON FeatureCollection, so the result drops straight into a map library. Each feature carries the matched address, its coordinates, an accuracy tier and a score. See Responses for every field.

You’ve built a geocoder for Ontario and queried it.

Use the interactive interface

og can also do all of this from the terminal. Run og with no arguments:

og

Pick a region from the catalog, build it, search it, and geocode CSV files, without remembering a flag.

Next steps

Build a Pack: several regions in one Pack, OpenAddresses, memory limits.
Serve the API: bind address, health checks and deploying.
Batch geocode a CSV: a whole file of addresses, offline.
API reference: every endpoint and parameter.