Architecture
Three orthogonal dimensions: Geographic Location × Data Category × Provider Capability.
On this page 3 sections
#Request pipeline
- Authenticate & validate: Verify client API key scopes (including all requested dataset scopes on
/v1/datasets) and input parameters. - Resolve location: Use supplied coordinates directly, or resolve unambiguous place names via
internal/georesolvewhenAPP_WEATHER_PLACE_RESOLVER=strictis enabled. - Discover eligible providers per category: Filter registered adapters by dataset capability, release profile (
lean_v1vsfull_experimental), geographic coverage, deployment use, credentials, health and 95% pre-flight quota gates. - Rank deterministically: Order eligible candidates by explicit operator priority and measured health (requiring ≥10 observations before applying health penalties in
lean_v1). - Execute & handle failures: Call the selected adapter with direct-dial SSRF protection, bounded timeouts, bulkheads and circuit breakers; automatically fail over to the next eligible provider on classified upstream or validation errors.
- Normalize & validate integrity: Convert units to Celsius/SI, enforce 25–50 km coordinate drift ceilings and 2-hour observation age limits, validate portable IANA timezones, and return versioned canonical schemas (or a
207 Multi-Statusbundle on partial multi-dataset availability).
#Package map
Trace these eleven logical modules through internal/routing (including datasets.go), internal/georesolve, internal/providerpolicy, internal/provider, internal/reliability, internal/normalization, internal/cache, internal/quota, internal/capability and providers/. Server routes are wired in internal/routing/router.go.
#Provenance and partial availability
Use meta.provider, meta.attribution, meta.cached and meta.fallback to inspect response origin. When requesting multiple categories for one location via GET /v1/datasets, UWA returns 200 OK if all categories succeed, or 207 Multi-Status with meta.partial=true containing successful data alongside structured per-category errors. Each request targets one geographic location; UWA does not expose a multi-location batch endpoint.
docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.