weatherreporter/docs/integrations/weatherapi.md

weatherapi External API

This document describes the public HTTP API exposed by weatherapi for external consumers.

Base URL

The service is typically served at your deployment host, for example:

• https://weather.api.rakestrawhome.com

All paths below are relative to the service root.

Common Conventions

Response envelope

All endpoints return a top-level envelope:

• data: endpoint payload or null when no current/latest resource is available.

JSON example:

{
  "data": {"...": "..."}
}

Output format

Supported via format query parameter (case-insensitive):

• json (default)
• xml
• text

Units

Supported via units query parameter (case-insensitive):

• metric (default)
• us

Endpoints that include unit-based numeric fields return either metric or US field variants depending on this value.

Precision

Supported where documented via precision query parameter:

• integer range: 0 to 2
• controls decimal rounding of numeric output fields

Timezone (tz / TZ)

Supported where documented:

• accepted values include:
  • IANA timezone names (example: America/Chicago)
  • common US abbreviations (example: CDT, EST)
  • UTC offsets in ±H, ±HH, or ±HH:MM (example: -5, +09:30)
  • aliases including Chicago and Stl
• tz and TZ are treated equivalently
• if both are provided, they must match exactly or the request fails

Timezone affects datetime rendering and day-slice filtering for /today and /tomorrow forecast routes.

Query validation

• Unknown query parameters are rejected with 400 Bad Request.
• Invalid parameter values are rejected with 400 Bad Request.

Error response body follows the service error envelope; exact fields may vary by error type.

Endpoints

GET /observations

Returns the latest weather observation.

Query parameters:

• units: metric | us
• format: json | xml | text
• precision: 0..2

Response data fields:

• stationId (string, optional)
• stationName (string, optional)
• timestamp (RFC3339 datetime, required)
• conditionCode (integer WMO code, required)
• isDay (boolean, optional)
• textDescription (string, optional)
• Metric mode fields:
  • temperatureC, dewpointC, windSpeedKmh, windGustKmh, barometricPressurePa, visibilityMeters, relativeHumidityPercent, apparentTemperatureC (number, optional)
  • windDirectionDegrees (number, optional)
• US mode fields:
  • temperatureF, dewpointF, windSpeedMph, windGustMph, barometricPressureInHg, visibilityMiles, relativeHumidityPercent, apparentTemperatureF (number, optional)
  • windDirectionDegrees (number, optional)
• presentWeather (array, optional)

GET /alerts/active

Returns the latest active alert run.

Query parameters:

• units: metric | us (accepted; does not materially alter alert payload)
• format: json | xml | text

Response data fields:

• Weather alert run object from canonical model (includes run metadata and active alerts list).

GET /conditions/current

Returns current conditions synthesized from latest observation/forecast data.

Query parameters:

• units: metric | us
• format: json | xml | text
• precision: 0..2

Response data fields:

• Common:
  • conditionText (string, optional)
  • isDay (boolean, optional)
  • relativeHumidityPercent (number, optional)
  • windDirectionDegrees (number, optional)
• Metric mode:
  • temperatureC, apparentTemperatureC, dewpointC, windSpeedKmh (number, optional)
• US mode:
  • temperatureF, apparentTemperatureF, dewpointF, windSpeedMph (number, optional)

Forecast endpoints

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

Query parameters:

• units: metric | us
• format: json | xml | text
• precision: 0..2
• tz or TZ: timezone selector

Day-slice routes:

• /today returns periods with period.startTime in the current calendar day for the resolved timezone.
• /tomorrow returns periods with period.startTime in the next calendar day for the resolved timezone.

Response data fields:

• Run-level:
  • locationId (string, optional)
  • locationName (string, optional)
  • issuedAt (RFC3339 datetime, required)
  • updatedAt (RFC3339 datetime, optional)
  • product (string, required; e.g. hourly, narrative)
  • latitude, longitude (number, optional)
  • Metric mode: elevationMeters (number, optional)
  • US mode: elevationFeet (number, optional)
  • periods (array, required)
• Period fields:
  • startTime, endTime (RFC3339 datetime, required)
  • name (string, optional)
  • isDay (boolean, optional)
  • conditionCode (integer WMO code, optional)
  • textDescription (string, optional)
  • Metric mode (optional):
    • temperatureC, temperatureCMin, temperatureCMax, dewpointC, windSpeedKmh, windGustKmh, barometricPressurePa, visibilityMeters, apparentTemperatureC, cloudCoverPercent, probabilityOfPrecipitationPercent, precipitationAmountMm, snowfallDepthMM, uvIndex, relativeHumidityPercent, windDirectionDegrees
  • US mode (optional):
    • temperatureF, temperatureFMin, temperatureFMax, dewpointF, windSpeedMph, windGustMph, barometricPressureInHg, visibilityMiles, apparentTemperatureF, cloudCoverPercent, probabilityOfPrecipitationPercent, precipitationAmountIn, snowfallDepthIn, uvIndex, relativeHumidityPercent, windDirectionDegrees

Notes:

• Narrative periods may omit conditionCode.
• Text format uses forecast-specific templates (hourly and narrative).

Discussion endpoints

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

Query parameters:

• units: metric | us (accepted; does not materially alter discussion payload)
• format: json | xml | text
• tz or TZ: timezone selector

Response data fields:

• /discussion:
  • officeId (string, optional)
  • officeName (string, optional)
  • product (string, required)
  • issuedAt (RFC3339 datetime, required)
  • updatedAt (RFC3339 datetime, optional)
  • keyMessages (array of string)
  • shortTerm (object, optional)
  • longTerm (object, optional)
• /discussion/key-messages:
  • officeId, officeName, product, issuedAt, updatedAt
  • keyMessages (array of string)
• /discussion/short-term:
  • officeId, officeName, product, issuedAt, updatedAt
  • shortTerm (object, optional)
• /discussion/long-term:
  • officeId, officeName, product, issuedAt, updatedAt
  • longTerm (object, optional)

Discussion section object fields:

• title (string, optional)
• narrative (string, optional)
• issuedAt (RFC3339 datetime, optional)

Examples

Observation (JSON, metric)

GET /observations?format=json&units=metric&precision=1

{
  "data": {
    "stationId": "KSTL",
    "timestamp": "2026-05-29T14:00:00Z",
    "conditionCode": 3,
    "isDay": true,
    "textDescription": "Partly cloudy",
    "temperatureC": 24.4,
    "windSpeedKmh": 17.2,
    "relativeHumidityPercent": 56.0
  }
}

Alerts (JSON)

GET /alerts/active?format=json

{
  "data": {
    "asOf": "2026-05-29T14:00:00Z",
    "alerts": []
  }
}

Current conditions (JSON, US)

GET /conditions/current?format=json&units=us&precision=1

{
  "data": {
    "conditionText": "Partly cloudy",
    "isDay": true,
    "temperatureF": 75.9,
    "apparentTemperatureF": 76.1,
    "windSpeedMph": 10.7,
    "relativeHumidityPercent": 56.0
  }
}

Forecast narrative (JSON, optional conditionCode)

GET /forecast/narrative?format=json&units=metric&precision=1&tz=America/Chicago

{
  "data": {
    "locationId": "nws-lsx-grid-90-74",
    "issuedAt": "2026-05-29T10:30:00-05:00",
    "product": "narrative",
    "periods": [
      {
        "startTime": "2026-05-29T13:00:00-05:00",
        "endTime": "2026-05-29T19:00:00-05:00",
        "name": "Today",
        "isDay": true,
        "textDescription": "Partly sunny, with a high near 81.",
        "temperatureC": 27.2,
        "windSpeedKmh": 18.0,
        "probabilityOfPrecipitationPercent": 10.0
      }
    ]
  }
}

Forecast hourly today (text)

GET /forecast/hourly/today?format=text&units=us&precision=1&tz=CDT

<plain text forecast output>

Discussion key messages (JSON)

GET /discussion/key-messages?format=json&tz=Chicago

{
  "data": {
    "officeId": "LSX",
    "product": "discussion",
    "issuedAt": "2026-05-29T09:25:00-05:00",
    "keyMessages": [
      "Scattered showers possible this evening.",
      "Warmer temperatures this weekend."
    ]
  }
}

Invalid timezone error example

GET /forecast/narrative?tz=not-a-timezone

{
  "error": {
    "code": "invalid_parameter",
    "message": "tz must be a valid timezone"
  }
}