# Qurmmius aggregate-data provider selection

This is the approved starting point for the GridPulse, EcoEcho, and SkySprout connectors. The connectors are **staged but disabled**: no external request runs until an owner enables the relevant environment flag, confirms the provider terms, and records a signed review.

## GridPulse — mobility context

- **Primary roadwork source:** [OpenStreetMap Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API), queried through a server-side cache for coarse corridor metadata and roadwork tags.
- **Weather context:** [Open-Meteo Forecast API](https://open-meteo.com/en/docs), using bounded coordinates supplied by an approved operator rather than live driver/device locations.
- **Controls:** OSM attribution, a single proxy origin, cache and request budgets, no GPS/device/driver identifiers, and operator review before a route signal is published.

## EcoEcho — environmental observations

- **Primary public measurement source:** [OpenAQ v3 measurements](https://docs.openaq.org/resources/measurements) for aggregate particulate readings and hourly rollups.
- **Community-only source:** a partner CSV or sensor gateway for noise and light, because those readings require local calibration and consent; no microphone or camera frames are accepted.
- **Controls:** station-level aggregation, calibration metadata, consent record, retention limit, and no operator/device identity in the payload.

## SkySprout — garden and micro-climate context

- **Weather and soil context:** [Open-Meteo Historical Weather API](https://open-meteo.com/en/docs/historical-weather-api) for bounded weather/soil variables and reproducible scenario context.
- **On-site readings:** a partner CSV or garden gateway for plot measurements, with a minimum three-station aggregation threshold before a trend can be shared.
- **Controls:** coarse plot labels, unit/measure validation, consent and stewardship review, no precise home coordinates, and no device/operator identifiers.

## Activation contract

Keep these values in Netlify environment variables, never in browser code or committed files:

```text
GRIDPULSE_PROVIDER_ENABLED=false
GRIDPULSE_PROVIDER_REVIEWED=true
GRIDPULSE_TERMS_REVIEWED=true
GRIDPULSE_STEWARD_APPROVED=true
GRIDPULSE_OVERPASS_BASE_URL=https://overpass-api.de/api/interpreter
GRIDPULSE_WEATHER_BASE_URL=https://api.open-meteo.com/v1/forecast
ECOECHO_PROVIDER_ENABLED=false
ECOECHO_OPENAQ_BASE_URL=https://api.openaq.org/v3
ECOECHO_PARTNER_GATEWAY_URL=
SKYSPROUT_PROVIDER_ENABLED=false
SKYSPROUT_PROVIDER_REVIEWED=true
SKYSPROUT_TERMS_REVIEWED=true
SKYSPROUT_STEWARD_APPROVED=true
SKYSPROUT_WEATHER_BASE_URL=https://archive-api.open-meteo.com/v1/archive
SKYSPROUT_PARTNER_GATEWAY_URL=
```

GridPulse and SkySprout each use four switches: provider enabled, provider
reviewed, terms reviewed, and steward approved. Internal review and steward
approval are recorded, but provider traffic remains disabled (`*_PROVIDER_ENABLED=false`).
The fetch adapter refuses upstream contact unless all four are true. See
[STAGED-PROVIDER-READINESS.md](/STAGED-PROVIDER-READINESS.md) for the
owner/second-approver and rollback checklist.

Before enabling any flag:

1. Confirm the provider’s current terms, attribution, rate limits, and data licensing.
2. Assign a data steward and record the aggregation boundary and retention period.
3. Run synthetic fixtures through SchemaForge and the QI product-pilot contract.
4. Run one signed staging request and review the request ID/audit record.
5. Obtain owner plus second-approver sign-off for provider enablement.

The UI’s provider selector documents these choices, but intentionally keeps `external_fetch_enabled: false` until this activation contract is completed.

The non-secret readiness snapshot is available at `GET /api/aggregate-provider-status`; it reports selections and enablement flags without contacting an upstream provider or exposing credentials.

## Where credentials come from

- **OpenAQ:** create an account at [OpenAQ Explorer](https://explore.openaq.org), then copy the API key from Settings. OpenAQ v3 expects the `X-API-Key` header and treats the key like a password. Store it as `ECOECHO_OPENAQ_API_KEY`.
- **Open-Meteo:** the public endpoint does not require a key for non-commercial use. For recurring commercial traffic, use the [commercial plan](https://open-meteo.com/en/pricing) and its dedicated endpoint/key, then store that value server-side (for example `SKYSPROUT_WEATHER_API_KEY` or `GRIDPULSE_WEATHER_API_KEY`).
- **OpenStreetMap Overpass:** the public endpoint does not issue a Qurmmius credential. It does require attribution, a distinctive `User-Agent`, caching, and conservative rate limits; recurring commercial use should use a self-hosted or paid Overpass service. Store only the approved base URL as `GRIDPULSE_OVERPASS_BASE_URL`.
- **Noise/light partner gateway:** the selected community partner supplies the URL and token. Store them as `ECOECHO_PARTNER_GATEWAY_URL` and the secret `ECOECHO_PARTNER_GATEWAY_TOKEN`.

## Where to enter them in Netlify

1. Open the Qurmmius project in Netlify and go to **Project configuration → Environment variables**.
2. Choose **Add a variable → Add a single variable** for each value. Set **Scope: Functions** and **Deploy context: Production**.
3. Mark API keys and tokens as **Contains secret values**. Never paste them into a page, browser console, `netlify.toml`, or a committed `.env` file.
4. Set the non-secret base URLs and provider flags only after the connector implementation and review are complete. Netlify applies variable changes after a new deploy.

The current site release includes a protected fetch adapter at `POST /api/aggregate-provider-fetch`. It requires a signed QI workspace, accepts only the bounded request shapes described above, enforces the EcoEcho sensor allowlist, caches summaries instead of raw upstream payloads, rate-limits requests, and records metadata-only audit entries. See [ECOECHO-PILOT.md](/ECOECHO-PILOT.md) for the calibration and consent record. The initial allowlisted smoke-test sensor is OpenAQ PM2.5 sensor `3920` at public location `2178`; verify sensor-specific coverage before publishing trends. GridPulse and SkySprout remain disabled; EcoEcho is enabled only for the reviewed OpenAQ path.