weatherfeeder/API.md

# weatherfeeder API (Wire Contract)

This document defines the stable, consumer-facing JSON contract emitted by weatherfeeder sinks.

weatherfeeder emits **events** encoded as JSON. Each event has:
- an **envelope** (metadata + schema identifier), and
- a **payload** whose shape is determined by `schema`.

Downstream consumers should:
1. parse the event envelope,
2. switch on `schema`, then
3. decode `payload` into the matching schema.

---

## Event envelope

All events are JSON objects with these fields:

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `id` | string | yes | Stable event identifier. Treat as opaque. |
| `schema` | string | yes | Schema identifier (e.g. `weather.observation.v1`). |
| `source` | string | yes | Provider/source identifier (stable within configuration). |
| `effectiveAt` | string (timestamp) | yes | RFC3339Nano timestamp indicating when this event is effective. |
| `payload` | object | yes | Schema-specific payload (see below). |

### Timestamp format

All timestamps are encoded as JSON strings using Go’s `time.Time` JSON encoding (RFC3339Nano).

Examples:
- `"2026-01-17T14:27:00Z"`
- `"2026-01-17T08:27:00-06:00"`

---

## Canonical schemas

weatherfeeder emits four canonical domain schemas:

- `weather.observation.v1`
- `weather.forecast.v1`
- `weather.forecast_discussion.v1`
- `weather.alert.v1`

Each payload is described below using the JSON field names as the contract.

### Raw upstream schemas

weatherfeeder sources also emit provider-specific raw schemas before normalization.
For this feature, the raw source schema is:

- `raw.nws.forecast_discussion.v1`
  - payload type: string
  - payload contents: exact fetched HTML response body

---

## Shared Conventions

- Timestamps are JSON strings in RFC3339Nano format.
- Optional fields are omitted when unknown (`omitempty` behavior).
- Numeric measurements are normalized to metric units:
  - `*C` = Celsius
  - `*Kmh` = kilometers/hour
  - `*Pa` = Pascals
  - `*Meters` = meters
  - `*Mm` = millimeters
  - `*Percent` = percent (0-100)
- `conditionCode` is a WMO weather interpretation code (`int`).
  - Unknown/unmappable is `-1`.
  - Downstream consumers should treat unknown codes as “unknown conditions” rather than failing decoding.
- For readability and stability, weatherfeeder rounds floating-point values in canonical payloads to
**4 digits after the decimal** during normalization.

---

## Schema: `weather.observation.v1`

Payload type: `WeatherObservation`

A `WeatherObservation` represents a point-in-time observation for a station/location.

### Fields

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `stationId` | string | no | Provider station/location identifier |
| `stationName` | string | no | Human station name |
| `timestamp` | timestamp string | yes | Observation timestamp |
| `conditionCode` | int | yes | WMO code (`-1` unknown) |
| `isDay` | bool | no | Day/night hint |
| `textDescription` | string | no | Human-facing short description |
| `temperatureC` | number | no | Celsius |
| `dewpointC` | number | no | Celsius |
| `windDirectionDegrees` | number | no | Degrees |
| `windSpeedKmh` | number | no | km/h |
| `windGustKmh` | number | no | km/h |
| `barometricPressurePa` | number | no | Pascals |
| `visibilityMeters` | number | no | Meters |
| `relativeHumidityPercent` | number | no | Percent |
| `apparentTemperatureC` | number | no | Celsius |
| `presentWeather` | array | no | Provider-specific structured weather fragments |

### Nested: `presentWeather[]`

Each `presentWeather[]` element:

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `raw` | object | no | Provider-specific JSON object |

---

## Schema: `weather.forecast.v1`

Payload type: `WeatherForecastRun`

A `WeatherForecastRun` is a single issued forecast snapshot for a location and a specific product
(hourly / narrative / daily). The run contains an ordered list of forecast periods.

### `product` values

`product` is one of:

- `"hourly"`
- `"narrative"`
- `"daily"`

### Fields

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `locationId` | string | no | Provider location identifier |
| `locationName` | string | no | Human name, if available |
| `issuedAt` | string (timestamp) | yes | When this run was generated/issued |
| `updatedAt` | string (timestamp) | no | Optional later update time |
| `product` | string | yes | One of `hourly`, `narrative`, `daily` |
| `latitude` | number | no | Degrees |
| `longitude` | number | no | Degrees |
| `elevationMeters` | number | no | meters |
| `periods` | array | yes | Chronological forecast periods |

### Nested: `periods[]` (`WeatherForecastPeriod`)

A `WeatherForecastPeriod` is valid for `[startTime, endTime)`.

| Field | Type | Required | Units / Notes |
|---|---:|:---:|---|
| `startTime` | string (timestamp) | yes | Period start |
| `endTime` | string (timestamp) | yes | Period end |
| `name` | string | no | Human label (often empty for hourly) |
| `isDay` | bool | no | Day/night hint |
| `conditionCode` | int | yes | WMO code (`-1` for unknown) |
| `textDescription` | string | no | Human-facing short phrase |
| `temperatureC` | number | no | °C |
| `temperatureCMin` | number | no | °C (aggregated products) |
| `temperatureCMax` | number | no | °C (aggregated products) |
| `dewpointC` | number | no | °C |
| `relativeHumidityPercent` | number | no | percent |
| `windDirectionDegrees` | number | no | degrees |
| `windSpeedKmh` | number | no | km/h |
| `windGustKmh` | number | no | km/h |
| `barometricPressurePa` | number | no | Pa |
| `visibilityMeters` | number | no | meters |
| `apparentTemperatureC` | number | no | °C |
| `cloudCoverPercent` | number | no | percent |
| `probabilityOfPrecipitationPercent` | number | no | percent |
| `precipitationAmountMm` | number | no | mm (liquid equivalent) |
| `snowfallDepthMm` | number | no | mm |
| `uvIndex` | number | no | unitless index |

---

## Schema: `weather.alert.v1`

Payload type: `WeatherAlertRun`

A `WeatherAlertRun` is a snapshot of *active* alerts for a location as-of a point in time.
A run may contain zero, one, or many alerts.

### Fields

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `locationId` | string | no | Provider location identifier |
| `locationName` | string | no | Human name, if available |
| `asOf` | string (timestamp) | yes | When the provider asserted this snapshot is current |
| `latitude` | number | no | Degrees |
| `longitude` | number | no | Degrees |
| `alerts` | array | yes | Active alerts (order provider-dependent) |

### Nested: `alerts[]` (`WeatherAlert`)

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `id` | string | yes | Provider-stable identifier (often a URL/URI) |
| `event` | string | no | Classification/event label |
| `headline` | string | no | Alert headline |
| `severity` | string | no | Example: Extreme/Severe/Moderate/Minor/Unknown |
| `urgency` | string | no | Example: Immediate/Expected/Future/Past/Unknown |
| `certainty` | string | no | Example: Observed/Likely/Possible/Unlikely/Unknown |
| `status` | string | no | Example: Actual/Exercise/Test/System/Unknown |
| `messageType` | string | no | Example: Alert/Update/Cancel |
| `category` | string | no | Example: Met/Geo/Safety/Rescue/Fire/Health/Env/Transport/Infra/CBRNE/Other |
| `response` | string | no | Example: Shelter/Evacuate/Prepare/Execute/Avoid/Monitor/Assess/AllClear/None |
| `response` | string | no | e.g. Shelter/Evacuate/Prepare/... |
| `description` | string | no | Narrative |
| `instruction` | string | no | What to do |
| `sent` | string (timestamp) | no | Provider-dependent |
| `effective` | string (timestamp) | no | Provider-dependent |
| `onset` | string (timestamp) | no | Provider-dependent |
| `expires` | string (timestamp) | no | Provider-dependent |
| `areaDescription` | string | no | Often a provider string |
| `senderName` | string | no | Provenance |
| `references` | array | no | Related alert references |

### Nested: `references[]` (`AlertReference`)

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `id` | string | no | Provider reference ID/URI |
| `identifier` | string | no | Provider identifier string, if distinct |
| `sender` | string | no | Sender |
| `sent` | string (timestamp) | no | Timestamp |

---

## Schema: `weather.forecast_discussion.v1`

Payload type: `WeatherForecastDiscussion`

A `WeatherForecastDiscussion` is an issued narrative bulletin for an NWS office.
It is distinct from `weather.forecast.v1`, which is period-based.

### Fields

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `officeId` | string | no | NWS office identifier, e.g. `LSX` |
| `officeName` | string | no | Human office name |
| `product` | string | yes | Currently `afd` |
| `issuedAt` | string (timestamp) | yes | Bulletin issue time |
| `updatedAt` | string (timestamp) | no | Optional page/update timestamp |
| `keyMessages` | array | no | Ordered key-message bullet list |
| `shortTerm` | object | no | Short-term discussion section |
| `longTerm` | object | no | Long-term discussion section |

### Nested: `shortTerm` / `longTerm`

| Field | Type | Required | Notes |
|---|---:|:---:|---|
| `qualifier` | string | no | Header qualifier such as `(Through Late Sunday Night)` |
| `issuedAt` | string (timestamp) | no | Optional section-local issue time |
| `text` | string | no | Paragraph-preserved prose text |

---

## Compatibility rules

- Consumers **must** ignore unknown fields.
- Producers (weatherfeeder) prefer **additive changes** within a schema version.
- Renames/removals/semantic breaks normally require a **schema version bump** (`weather.*.v2`); pre-1.0 projects may choose in-place changes.

---

## Examples

### Observation event (`weather.observation.v1`)

```json
{
  "id": "nws:KSTL:2026-01-17T14:00:00Z",
  "schema": "weather.observation.v1",
  "source": "nws_observation",
  "effectiveAt": "2026-01-17T14:00:00Z",
  "payload": {
    "stationId": "KSTL",
    "timestamp": "2026-01-17T14:00:00Z",
    "conditionCode": 1,
    "textDescription": "Mainly Sunny",
    "temperatureC": 3.25,
    "windSpeedKmh": 18.5
  }
}
```

### Forecast event (`weather.forecast.v1`)

```json
{
  "id": "openmeteo:38.63,-90.20:2026-01-17T13:00:00Z",
  "schema": "weather.forecast.v1",
  "source": "openmeteo_forecast",
  "effectiveAt": "2026-01-17T13:00:00Z",
  "payload": {
    "locationName": "St. Louis, MO",
    "issuedAt": "2026-01-17T13:00:00Z",
    "product": "hourly",
    "latitude": 38.63,
    "longitude": -90.2,
    "periods": [
      {
        "startTime": "2026-01-17T14:00:00Z",
        "endTime": "2026-01-17T15:00:00Z",
        "conditionCode": 2,
        "textDescription": "Partly Cloudy",
        "temperatureC": 3.5,
        "probabilityOfPrecipitationPercent": 10
      }
    ]
  }
}
```

### Alert event (`weather.alert.v1`)

```json
{
  "id": "nws:alerts:2026-01-17T14:10:00Z",
  "schema": "weather.alert.v1",
  "source": "nws_alerts",
  "effectiveAt": "2026-01-17T14:10:00Z",
  "payload": {
    "asOf": "2026-01-17T14:05:00Z",
    "alerts": [
      {
        "id": "https://api.weather.gov/alerts/abc123",
        "event": "Winter Weather Advisory",
        "headline": "Winter Weather Advisory issued January 17 at 8:05AM CST",
        "severity": "Moderate",
        "description": "Mixed precipitation expected...",
        "expires": "2026-01-18T06:00:00Z"
      }
    ]
  }
}
```