# Weatherkind

> Weatherkind is a weather platform that runs its own forecast engine from raw
> NOAA and ECMWF model output, terrain data, radar, satellite observations, and
> quality-controlled weather-station observations.

Base URL: `https://api.weatherkind.com`

Machine-readable contract: `GET /v1/openapi.json` (OpenAPI 3.1).

## Conventions

- Send JSON with `Content-Type: application/json`.
- Authenticate with `Authorization: Bearer {api_key}`.
- Keep API keys on a backend or edge proxy.
- Data endpoints return their result directly, without a `data` envelope.
- Responses include top-level `updated_at`, `stale`, and `warnings` fields.
- `stale: true` means cached data was served during upstream degradation.
- Request `units` as `"metric"`, `"us"`, or `"si"`. Put individual choices
  such as pressure or elevation in `unit_overrides`.
- Instants are ISO-8601 UTC timestamps. Daily dates are local `YYYY-MM-DD`
  dates in the resolved location time zone. Date ranges include both `start`
  and `end`; timestamp ranges include `start` and exclude `end`.
- Public responses use named sections and flat records. They do not use a
  top-level timelines collection or nested values objects; non-current
  forecast sections contain their resolved range and flat entries.

Public catalogs: `GET /v1/forecast/variables`,
`GET /v1/historical/variables`, and `GET /v1/accuracy/catalog`.

## Forecast

`POST /v1/forecast` accepts named forecast sections. If no section is sent,
the API returns a useful default forecast.

```json
{
  "location": { "latitude": 39.1911, "longitude": -106.8175 },
  "timezone": "auto",
  "units": "us",
  "unit_overrides": { "pressure": "hPa" },
  "current": { "variables": ["temperature", "condition", "wind_speed"] },
  "quarter_hourly": {
    "hours": 6,
    "variables": ["temperature", "precipitation_probability"]
  },
  "hourly": {
    "hours": 48,
    "past_hours": 6,
    "variables": ["temperature", "wind_speed"]
  },
  "daily": {
    "days": 10,
    "variables": ["temperature_max", "temperature_min", "condition"]
  }
}
```

Every section takes `variables`. `quarter_hourly` accepts 1–48 `hours`.
`hourly` accepts 1–384 `hours` and 0–48 optional `past_hours`. `daily` accepts
1–16 `days`, or exact local `start` and `end` dates (both inclusive, so
`start` equal to `end` is a single day).

The response mirrors requested section names. `current` is one flat object.
`quarter_hourly`, `hourly`, and `daily` are objects with a `range` (the
resolved window) and `entries`, an array of flat records. Subdaily
records have `time`; daily records have `date`. `updated_at` may be null. `location.forecast_elevation_m`
is the representative elevation used by the forecast. Weather responses do
not resolve or return a separate ground elevation.

Variables by section:

- `current`: `temperature`, `apparent_temperature`, `condition`, `humidity`,
  `pressure`, `wind_speed`, `uv_index`, `air_quality_index`, `dew_point`
- `quarter_hourly`: `temperature`, `apparent_temperature`, `condition`,
  `wind_speed`, `wind_direction`, `precipitation`, `rain`, `snow`,
  `precipitation_probability`, `cloud_cover`
- `hourly`: current fields plus `wind_gust`, `wind_direction`, precipitation
  fields, and `cloud_cover`
- `daily`: `temperature_max`, `temperature_min`, `condition`, `precipitation`,
  `rain`, `snow`, `precipitation_probability`, `sunrise`, `sunset`

## Nowcast

`POST /v1/nowcast` accepts `location`, optional `timezone`, optional `units`,
optional `unit_overrides`, and optional `variables` (defaults to every nowcast
variable: condition, precipitation, precipitation_rate, rain, snow,
precipitation_probability, confidence, hail_probability, hail_size,
lightning_probability, source). It returns a fixed two-hour precipitation
product with top-level `start`, `end`, `status`, `minutes`, `radar_pending`,
and `onset_uncertainty_minutes`. Each `minutes[]` object is flat, begins
with `time`, and contains only the selected variables. Poll it independently from the slower-changing forecast and honor
`Retry-After` when present.

## Outlook

`POST /v1/outlook` returns a daily climate outlook for local dates 15–365 days
ahead:

```json
{
  "location": { "latitude": 39.1911, "longitude": -106.8175 },
  "units": "us",
  "start": "2026-08-15",
  "end": "2026-09-15",
  "variables": ["temperature_max", "temperature_min", "precipitation"]
}
```

`start` and `end` are both inclusive local dates. The response `daily`
section is an object with the resolved `range` and an `entries` array of flat
records. Use `/v1/forecast` for the next two weeks and `/v1/outlook` for
broader seasonal tendencies.

## Historical observations

`POST /v1/historical` accepts daily dates and variables directly:

```json
{
  "location": { "latitude": 39.1911, "longitude": -106.8175 },
  "timezone": "auto",
  "units": "us",
  "start": "2025-06-01",
  "end": "2025-07-01",
  "variables": ["temperature_max", "temperature_min", "precipitation"],
  "include": ["stations", "sources"]
}
```

It returns top-level `start`, `end`, and a flat `daily` array. `start` and
`end` are both inclusive, so one day is `start` equal to `end`. Dates must be
completed local days (yesterday or earlier in the location's time zone). General queries may span up to 50 years; queries that
include `air_quality_index` may span at most 366 days. At most 25,000 scalar
values may be requested. Supported variables are `temperature_max`,
`temperature_min`, `precipitation`, `rain`, `snow`, and `air_quality_index`.
Missing observations are returned as `null` with warnings.

## Accuracy

`POST /v1/accuracy` returns historical forecast-performance statistics, not
current weather:

```json
{
  "scope": {
    "type": "local",
    "location": { "latitude": 39.1911, "longitude": -106.8175 }
  },
  "days": 30,
  "units": "us",
  "hourly": {
    "lead_hours": [1, 6, 12, 24],
    "variables": ["temperature", "precipitation_probability"]
  },
  "daily": {
    "lead_days": [1, 3, 7],
    "variables": ["temperature_max", "temperature_min"]
  },
  "compare_to": ["persistence"],
  "include": ["stations"]
}
```

Scopes are `local`, `region`, or `network`. `days` defaults to 30 and accepts
7–365. Sections are `minutely`, `hourly`, and `daily`, with explicit
`lead_minutes`, `lead_hours`, and `lead_days`. The response uses the same named
sections; each flat record begins with the corresponding lead field and then
contains requested variable metrics. `coverage.available: false` is a valid
result, not zero error. `compare_to: ["persistence"]` adds baseline metrics
and skill scores.

## Alerts, elevation, and map tiles

- `POST /v1/alerts` accepts `location` and optional `include: ["geometry"]`.
  It returns `alerts`, `updated_at`, `stale`, and `warnings`.
- `POST /v1/elevation` accepts `location`, string `units`, optional
  `unit_overrides`, and optional `include: ["terrain_profile"]`. It returns
  ground elevation and optional valley, mid-slope, and peak representatives.
- `GET /v1/map-tiles/{layer}/{z}/{x}/{y}` returns a cacheable 256 × 256 PNG
  tile. Use map tiles for rendering and `/v1/forecast` for numeric values.

## Errors and retries

Validation failures use RFC 9457 problem JSON with status `422` and structured
field errors. `401` means missing or invalid credentials; `403` means missing
scope or plan entitlement; `429` means wait for `Retry-After`; and `5xx` may be
retried with bounded exponential backoff and jitter.

## Guidance for AI agents

1. Read this file, the full static docs, and the OpenAPI contract.
2. Use forecast for the next two weeks, outlook beyond that, and nowcast for
   minute precipitation.
3. Use historical for observed daily weather and accuracy for forecast error.
4. Request only needed named sections and variables.
5. Surface `stale` when freshness matters.
6. For consequential recommendations, query accuracy for the same coordinates
   and explain sample coverage and the relevant error metric.

## Pages

- API overview and pricing: https://weatherkind.com/developers
- Full reference: https://weatherkind.com/developers/docs
- Agent guide: https://weatherkind.com/developers/agents
- OpenAPI: https://api.weatherkind.com/v1/openapi.json