weatherapi/docs/api.md

weatherapi HTTP API

This is the canonical public HTTP contract for weatherapi. The service is a read-only API over the latest weather records available in the configured weatherfeeder-populated Postgres database.

Base URL

All paths are relative to the deployment root:

http://localhost:8080

Use your deployment host in production.

Authentication

weatherapi does not implement authentication or authorization. Put access control in front of the service when a deployment requires it.

Response Envelope

Successful JSON and XML responses use a top-level envelope:

{
  "data": {}
}

When no latest/current resource exists, the request still succeeds and returns data: null.

Text responses are rendered from endpoint-specific templates. When the payload is missing, the templates return a short no-data message.

Formats

Every implemented endpoint can produce:

Format	Media type
json	application/json
xml	application/xml
text	text/plain

Format selection is:

1. format query parameter;
2. Accept header;
3. configured server.default_format.

format values are case-insensitive. Unsupported formats return 406 Not Acceptable with an error envelope.

Shared Query Rules

Unknown query parameters are rejected with 400 Bad Request.

Parameter	Values	Default	Supported on
format	json, xml, text	configured default	all endpoints
units	metric, us	metric	all endpoints
precision	integer 0 through 2	0	observations, current conditions, forecasts
tz or TZ	timezone selector	UTC/no conversion	forecasts, discussions, weather stories

units, format, and precision values are normalized case-insensitively where applicable. units=metric returns metric field names; units=us returns US-customary field names for unit-bearing payloads. Alerts, discussions, and weather stories accept units but their current payload fields are not materially changed by it.

precision controls numeric rounding. The default 0 rounds to whole numbers. precision is rejected on alerts, discussions, and weather stories.

Timezone selectors accepted by tz / TZ:

• IANA timezone names such as America/Chicago;
• common US abbreviations such as CDT, CST, EDT, EST, MDT, MST, PDT, and PST;
• UTC offsets in +H, +HH, +HH:MM, -H, -HH, or -HH:MM form, bounded to -14:00 through +14:00;
• aliases Chicago and Stl, both mapped to America/Chicago.

If both tz and TZ are provided, their values must match case-insensitively. Timezone conversion affects rendered timestamps and forecast /today and /tomorrow day-slice filtering. Without a timezone parameter, day-slice routes use UTC.

Errors

API errors use a stable error envelope:

{
  "error": {
    "code": "invalid_parameter",
    "message": "..."
  }
}

Implemented API error statuses:

Status	Code	Cause
400 Bad Request	invalid_parameter	unknown query parameter, invalid parameter value, invalid timezone, conflicting tz / TZ, or unsupported parameter on a route
406 Not Acceptable	unsupported_format	requested response format is not supported by the endpoint/renderers

Unhandled service or database errors are returned as server errors by the runtime.

Behavior Not Implemented

weatherapi does not implement pagination, cache-control headers, rate-limit headers, idempotency keys, retries, writes, or historical browsing outside the implemented latest-resource and forecast day-slice routes.

Endpoints

Observations

GET /observations

Returns the latest weather observation.

Query parameters: format, units, precision.

Metric data fields:

Field	Type	Notes
stationId, stationName	string	optional
timestamp	RFC3339 datetime	required when data is not null
conditionCode	integer	WMO weather code
isDay	boolean	optional
textDescription	string	optional
temperatureC, dewpointC, apparentTemperatureC	number	optional
windDirectionDegrees, windSpeedKmh, windGustKmh	number	optional
barometricPressurePa, visibilityMeters	number	optional
relativeHumidityPercent	number	optional
presentWeather	array	optional

US mode replaces unit-bearing fields with temperatureF, dewpointF, apparentTemperatureF, windSpeedMph, windGustMph, barometricPressureInHg, and visibilityMiles. Direction and percentage fields keep the same names.

Example:

GET /observations?units=us&precision=1

Current Conditions

GET /conditions/current

Returns current conditions aggregated from recent observations rows. The implemented observation window is 30 minutes.

Query parameters: format, units, precision.

Common data fields:

Field	Type	Notes
conditionText	string	optional text derived from WMO code and day/night flag
isDay	boolean	optional
relativeHumidityPercent	number	optional
windDirectionDegrees	number	optional

Metric fields: temperatureC, apparentTemperatureC, dewpointC, windSpeedKmh.

US fields: temperatureF, apparentTemperatureF, dewpointF, windSpeedMph.

Example:

GET /conditions/current?format=json&precision=0

Active Alerts

GET /alerts/active

Returns the latest active-alert snapshot.

Query parameters: format, units.

Run data fields:

Field	Type	Notes
locationId, locationName	string	optional
asOf	RFC3339 datetime	required when data is not null
latitude, longitude	number	optional
alerts	array	active alerts, possibly empty

Alert fields include id, event, headline, severity, urgency, certainty, status, messageType, category, response, description, instruction, sent, effective, onset, expires, areaDescription, senderName, and references. Most alert fields are optional except id when an alert item is present.

Reference fields are id, identifier, sender, and sent.

Example:

GET /alerts/active?format=text

Forecasts

GET /forecast/hourly
GET /forecast/hourly/today
GET /forecast/hourly/tomorrow
GET /forecast/narrative
GET /forecast/narrative/today
GET /forecast/narrative/tomorrow

Returns the latest hourly or narrative forecast run. /today and /tomorrow return a copy of the latest run with periods filtered by each period's startTime in the resolved timezone. If no periods match, data remains an object and periods is an empty array.

Query parameters: format, units, precision, tz / TZ.

Run data fields:

Field	Type	Notes
locationId, locationName	string	optional
issuedAt	RFC3339 datetime	required when data is not null
updatedAt	RFC3339 datetime	optional
product	string	hourly or narrative for implemented routes
latitude, longitude	number	optional
elevationMeters or elevationFeet	number	optional, depends on units
periods	array	ordered forecast periods

Metric period fields:

startTime, endTime, name, isDay, conditionCode, textDescription, temperatureC, temperatureCMin, temperatureCMax, dewpointC, relativeHumidityPercent, windDirectionDegrees, windSpeedKmh, windGustKmh, barometricPressurePa, visibilityMeters, apparentTemperatureC, cloudCoverPercent, probabilityOfPrecipitationPercent, precipitationAmountMm, snowfallDepthMm, and uvIndex.

US mode uses the same non-unit fields and replaces unit-bearing fields with temperatureF, temperatureFMin, temperatureFMax, dewpointF, windSpeedMph, windGustMph, barometricPressureInHg, visibilityMiles, apparentTemperatureF, precipitationAmountIn, snowfallDepthIn, and elevationFeet at run level.

startTime and endTime are required for each period. Other period fields are optional, including conditionCode; narrative forecasts may omit it.

Examples:

GET /forecast/hourly?units=us&precision=1&TZ=-5
GET /forecast/narrative/tomorrow?format=text&tz=Chicago

Forecast Discussions

GET /discussion
GET /discussion/key-messages
GET /discussion/short-term
GET /discussion/long-term

Returns the latest forecast discussion or a focused subresource.

Query parameters: format, units, tz / TZ.

Full discussion data fields:

Field	Type	Notes
officeId, officeName	string	optional
product	string	currently afd from weatherfeeder data
issuedAt	RFC3339 datetime	required when data is not null
updatedAt	RFC3339 datetime	optional
keyMessages	array of strings	optional
shortTerm, longTerm	object	optional section objects

Discussion section fields are qualifier, issuedAt, and text, all optional.

Subresources return the same metadata plus only their focused field: keyMessages, shortTerm, or longTerm.

Example:

GET /discussion/short-term?format=text&tz=CDT

Weather Stories

GET /weatherstories
GET /weatherstories/latest

/weatherstories returns the latest weather-story run and its ordered stories. /weatherstories/latest returns the latest individual story.

Query parameters: format, units, tz / TZ.

Run data fields:

Field	Type	Notes
officeId	string	optional
asOf	RFC3339 datetime	required when data is not null
stories	array	ordered story objects

Story fields:

Field	Type	Notes
officeId	string	optional
startTime, endTime, updatedAt	RFC3339 datetime	required when a story is present
title, description, altText, downloadUrl	string	optional
priority	boolean	required when a story is present
order	integer	required when a story is present

Examples:

GET /weatherstories?tz=America/Chicago
GET /weatherstories/latest?format=xml

Copyable Requests

See examples/requests.http for a compact set of requests covering the implemented endpoint families.