Documentation
DocumentationQuickstart
DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY

Quickstart

Supply an upstream key, run your own gateway, then request data by coordinates or place name using the UWA v1 API.

ONE GATEWAYCoordinates → eligible provider → canonical responseWhy UWA
On this page 5 sections

#Requirements

Use Go 1.27.3 or a newer supported security-patched release for source builds (the go 1.22 directive in go.mod is a language syntax compatibility floor, not a deployment toolchain recommendation). A verified provider credential, applicable licence permission, quota budget and operator policy are necessary for a successful upstream weather call. Development uses in-memory storage by default; the production profile requires PostgreSQL 16 and Redis 7.

#Build and check offline

Run from the root of the gateway repository (not the website directory). Both commands validate configuration and policy without opening external network connections:

go version
go run ./cmd/gateway --check-config
go run ./cmd/uapctl doctor --json
go test ./...
go build -o gateway ./cmd/gateway

#Configure an upstream and development key

Set OPENWEATHER_API_KEY or WEATHERAPI_API_KEY with an authorized key in your local environment. For local loopback development with memory storage, UWA does not seed a hardcoded default key—explicitly set APP_DEV_CLIENT_KEY (24–512 characters) on loopback development only, or provision a scoped key in PostgreSQL with uapctl create-key.

export APP_ENV="development"
export APP_DB_DRIVER="memory"
export APP_BIND_HOST="127.0.0.1"
export APP_DEV_CLIENT_KEY="dev_local_only_replace_with_24_plus_chars"
export OPENWEATHER_API_KEY="YOUR_UPSTREAM_KEY"
go run ./cmd/gateway

#Health, single-category, and multi-category requests

In a separate terminal, check the process and query either a single category (/v1/weather) or multiple categories in one call (/v1/datasets):

curl "http://127.0.0.1:8080/health"

# Single-category current weather for Bhilai, India:
curl -H "X-API-Key: YOUR_GATEWAY_KEY" \
  "http://127.0.0.1:8080/v1/weather?lat=21.21&lon=81.43"

# Multi-category request (weather + 24 forecast points) in one call:
curl -H "X-API-Key: YOUR_GATEWAY_KEY" \
  "http://127.0.0.1:8080/v1/datasets?datasets=weather,forecast&lat=21.21&lon=81.43&forecast.points=24"
No invented success response

A 200 response is not guaranteed until an eligible live provider, valid key, quota budget, connectivity and policy are configured. A healthy process does not prove upstream data availability.

#Troubleshoot

If you receive 401/403, check your gateway client key and required scopes. If you receive 503 AUTH_BACKEND_UNAVAILABLE, check PostgreSQL connectivity. If no provider is eligible, run go run ./cmd/uapctl doctor --json and check enablement flags, credentials, location policy, deployment use and quotas. See diagnostics.

Canonical contracts: docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.

Search local documentation. No external requests.

↑↓ to move · Enter to openESC to close