wofclient

README

go-wof-client

A small Go client for Who's-On-First (WOF) SQLite gazetteer distributions — per-country .db.bz2 administrative-places dumps.

Install

go get github.com/olehmushka/go-wof-client

Usage

sum, err := wofclient.Download(ctx, govapicore.NewHTTPClient(0), distURL, "/tmp/us.db")

db, err := wofclient.Open("/tmp/us.db")
defer db.Close()

err = db.Placetype(ctx, "country", func(f wofclient.Feature) error {
    // f.Country, f.IsCurrent, f.Body (a WOF GeoJSON Feature — decode it yourself)
    return nil
})

Scope

This client covers downloading + decompressing a distribution and reading its spr/geojson tables by placetype. It does not interpret WOF's own property schema (wof:id, wof:hierarchy, wof:name, ...) into any application's domain model — that mapping is application-specific and belongs in the caller.

Notes

Built on go-govapi-core for the User-Agent convention, and modernc.org/sqlite (a cgo-free database/sql driver) to read the distribution. Both the download/decompress mechanics and the SQL query mirror an already-shipped, already-verified integration against this same distribution format in go-oikumenea's internal/hermenea/fetcher/fetcher.go (WOFSQLite) and internal/hermenea/wof/mapper.go (its D-GeoPlaces / M16 geo-places pipeline) — this package is that integration's fetch+read layer, extracted and generalized; the WOF-property-to-application-field mapping stays in the caller.

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package wofclient is a small client for Who's-On-First (WOF) SQLite gazetteer distributions (https://whosonfirst.org) — per-country `.db.bz2` administrative-places dumps.

It covers two things: downloading + decompressing a distribution to a local SQLite file (Download), and reading its `spr`/`geojson` tables by placetype (DB.Placetype). It does not interpret WOF's own property schema (wof:id, wof:hierarchy, wof:name, ...) into any application's domain model — that mapping is application-specific and belongs in the caller, not in a generic client to this distribution format.

Both the download/decompress mechanics and the SQL query mirror an already-shipped, already-verified integration against this same distribution format: https://github.com/olehmushka/go-oikumenea/blob/main/internal/hermenea/fetcher/fetcher.go (its `WOFSQLite` streaming fetcher) and https://github.com/olehmushka/go-oikumenea/blob/main/internal/hermenea/wof/mapper.go (its D-GeoPlaces / M16 geo-places pipeline, which reads the exact query this package runs) — this package is that integration's fetch+read layer, extracted and generalized; the WOF-property-to-application-field mapping stays in the caller.

Index

• Constants
• func Download(ctx context.Context, client *http.Client, url, dest string) (string, error)
• type DB
  • func Open(path string) (*DB, error)
  • func (d *DB) Close() error
  • func (d *DB) Placetype(ctx context.Context, placetype string, yield func(Feature) error) error
• type Feature

Constants

const DefaultUserAgent = "go-wof-client/0.1 (+https://github.com/olehmushka/go-wof-client)"

DefaultUserAgent identifies this client when UserAgentEnv is unset.

const UserAgentEnv = "WOF_CLIENT_USER_AGENT"

UserAgentEnv lets an operator override the outbound User-Agent with their own contact.

Functions

func Download

func Download(ctx context.Context, client *http.Client, url, dest string) (string, error)

Download streams a WOF distribution's `.db.bz2` from url, bzip2-decompresses it to dest (a local file path), and returns the sha256 checksum of the decompressed bytes (hex-encoded). The decompressed bytes are streamed straight to disk — a WOF distribution can be gigabytes of geometry, so this never buffers the whole thing in memory. client's own timeout (or the caller's ctx deadline, if client has none) governs how long this may run; a planet-scale distribution can take a while, so a caller downloading one of those should use an unbounded client (govapicore.NewHTTPClient(0)) bounded by ctx instead.

Types

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB wraps an opened WOF SQLite distribution for read access.

func Open

func Open(path string) (*DB, error)

Open opens a WOF SQLite distribution at path (as produced by Download, or any WOF `.db` file already decompressed by other means).

func (*DB) Close

func (d *DB) Close() error

Close closes the underlying database handle.

func (*DB) Placetype

func (d *DB) Placetype(ctx context.Context, placetype string, yield func(Feature) error) error

Placetype streams every current-geometry feature for one WOF placetype (e.g. "country", "region", "county", "locality"), ordered by the distribution's internal id (parent-first within a single placetype's insert order — WOF's own convention), calling yield once per row so a caller can page without loading a whole placetype into memory. yield returning an error stops iteration and that error is returned.

type Feature

type Feature struct {
	Country   string
	IsCurrent int
	Body      []byte
}

Feature is one WOF `spr` row joined to its canonical GeoJSON body — the raw shape; Body is a WOF GeoJSON Feature (properties + geometry) the caller decodes itself.