# OpenWeather Integration Notes

## Purpose

This document describes the OpenWeather current-weather usage implemented by
`weatherfeeder`. It is for developers and operators maintaining OpenWeather
source URLs, normalizers, fixtures, and tests.

General config syntax belongs in [configuration](../config.md). Emitted JSON
events are documented in [event wire contract](events.md).

## Implemented Driver

| Driver | Kind | Raw schema | Canonical schema |
| --- | --- | --- | --- |
| `openweather_observation` | `observation` | `raw.openweather.current.v1` | `weather.observation.v1` |

Only current-weather observation polling is registered for OpenWeather.

## Config Requirements

The driver requires HTTP source params:

- `url`
- `user_agent`

The shared HTTP helper also accepts `conditional`, `http_timeout`, and
`http_response_body_limit_bytes`. Conditional requests are enabled by default;
an upstream `304 Not Modified` response emits no event for that poll.

The configured URL must include:

```text
units=metric
```

Startup fails if `units` is omitted or set to another value. Keep OpenWeather
API keys out of committed configs. Use local config management or deployment
secrets for the `appid` query parameter.

## Upstream Shape Used

The source emits the full current-weather JSON payload as a raw event. The
normalizer uses:

- `coord.lat`, `coord.lon`;
- primary `weather[0]` condition ID, description, and icon;
- `main.temp`, `main.feels_like`, `main.pressure`, `main.humidity`, and
  optional `main.sea_level`;
- `visibility`;
- `wind.speed`, `wind.deg`, and `wind.gust`;
- `dt`;
- `sys.sunrise` and `sys.sunset`;
- `id` and `name`.

## Accept Header

OpenWeather sources request:

```text
application/json
```

## Time Handling

Source events set `effective_at` from `dt` when it is present and positive.
The normalizer also uses `dt` as the canonical observation timestamp and
normalized effective time.

## Mapping Notes

Metric units are required so canonical unit conversion is deterministic:

- `main.temp` and `main.feels_like` are treated as Celsius;
- `wind.speed` and `wind.gust` are treated as meters per second and converted to
  kilometers per hour;
- pressure values are treated as hPa and converted to Pa.

The primary condition is `weather[0]`. OpenWeather condition IDs are mapped into
the canonical WMO code vocabulary. The human text description is preserved from
the provider description.

Day/night is inferred from the OpenWeather icon suffix when available, otherwise
from sunrise and sunset bounds.

The station ID uses the OpenWeather city ID when present. If no city ID is
present, weatherfeeder synthesizes an ID from coordinates. The station name uses
the provider `name`, falling back to `OpenWeatherMap` when blank.

## Failure Behavior

Constructor validation failures stop daemon startup. Polling also re-checks the
metric-unit requirement before fetching. HTTP failures are returned to the
scheduler. Metadata decoding failures in the source still allow raw payload
emission when the HTTP response itself succeeded.

## Tests To Inspect

- `internal/sources/openweather/source_test.go`
- `internal/normalizers/openweather/*_test.go`
- `internal/providers/openweather/*_test.go`