Google Maps Geocoding API adapter.

Requires a valid Google Maps API key with the Geocoding API enabled.

Usage:
  (def adapter (create-google-adapter {:api-key "AIza..."}))
  (geocode adapter {:address "Damrak 1, Amsterdam"})

Mapbox Geocoding API adapter.

Requires a valid Mapbox access token.
Note: Mapbox returns coordinates as [longitude, latitude] (GeoJSON order).

Usage:
  (def adapter (create-mapbox-adapter {:api-key "pk.eyJ1..."}))
  (geocode adapter {:address "Damrak 1, Amsterdam"})

OpenStreetMap Nominatim geocoding adapter.

Rate limit: 1 request per second (OSM usage policy requires this).
No API key required. A descriptive User-Agent header is mandatory.

Usage:
  (def adapter (create-nominatim-adapter {:user-agent "MyApp/1.0 (contact@example.com)"}))
  (geocode adapter {:postcode "1012 JS" :city "Amsterdam"})

PDOK Locatieserver adapter: Dutch addresses from the BAG.

No API key. Netherlands only; a query for another country is a miss, so a
fallback chain moves on. A postcode with a house number is looked up exactly.

Usage:
  (def adapter (create-pdok-adapter {}))
  (geocode adapter {:postcode "1012 JS" :house-number 1})

Rate limiting and response parsing shared by the provider adapters.

DB-backed geocoding cache implementing GeoCacheProtocol.

Uses a `geo_cache` table with a SHA-256 address hash as primary key.
Run the migration in resources/wagoe/geo/migrations/001-geo-cache.sql
before using this component.

TTL is enforced at lookup time by comparing `created_at` to `NOW() - cache-ttl`.

Integrant wiring for the geo module.

Config key: :wagoe/geo-service

Example (single provider, no caching):
  :wagoe/geo-service
  {:provider  :openstreetmap
   :user-agent "MyApp/1.0 (contact@example.com)"}

Example (Dutch addresses from postcode + house number, no key):
  :wagoe/geo-service
  {:provider :pdok}

Example (Google with DB cache):
  :wagoe/geo-service
  {:provider   :google
   :api-key    #env WAG_GEO_API_KEY
   :cache-ttl  86400
   :cache?     true}

Example (fallback chain):
  :wagoe/geo-service
  {:provider   [:openstreetmap :google]
   :api-key    #env WAG_GEO_API_KEY
   :cache-ttl  86400
   :cache?     true}

:cache? true caches lookups in the geo_cache table, through the
:wagoe/db-context the module wires itself. An explicit :db-ctx still works.

:timeout-ms (default 3000) bounds each provider's connect and read.
The component is a service/GeoService; a call can keep to some of the
providers with {:only #{:pdok}}.

Public API for the geo module.

Entry points:
- geocode!         — forward geocoding with cache-first lookup
- reverse-geocode! — reverse geocoding (no caching, coordinates not hashed)
- distance         — pure Haversine distance delegate

The first two take {:only #{:pdok}} to use only the named providers. The
component, GeoService, answers them through ports/GeoServiceProtocol too.

`geocode!` flow:
  1. Compute query-hash from the AddressQuery (and :only, when given)
  2. If a cache is configured, attempt cache-lookup
  3. On cache miss, iterate providers until one returns a result
  4. Cache-store! the result (if cache configured and result non-nil)
  5. Return result or nil