{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/smarterweather-com/json-schema/smarterweather-com-climate-normals-schema.json",
  "title": "ClimateNormals",
  "description": "Day-of-year climate normals for a point, read from the gridded normals\nacross CONUS and otherwise from the nearest station with records. The\nresolved station is always named, whichever supplied the values.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/smarterweather-com-climate-api-openapi.yml#/components/schemas/ClimateNormals",
  "type": "object",
  "required": [
    "station",
    "meta",
    "days"
  ],
  "properties": {
    "station": {
      "$ref": "#/$defs/ClimateNormalsStation"
    },
    "meta": {
      "$ref": "#/$defs/ClimateNormalsMeta"
    },
    "days": {
      "type": "array",
      "description": "Per-day normals series, in requested date order.",
      "items": {
        "$ref": "#/$defs/ClimateNormalsDay"
      }
    },
    "location": {
      "$ref": "#/$defs/Location",
      "description": "Resolved location, as `/v1/weather` returns it. Present when the\nplace was resolved: always for a `zip` or `location` request, and\nfor `lat`/`lon` when the coverage check's lookup answered in time\n(omitted when that check fails open).\n"
    }
  },
  "$defs": {
    "ClimateNormalsDay": {
      "type": "object",
      "description": "One day-of-year slice. Fields are omitted when no normal is available,\nwhich is not the same as a value of zero. `normal_precip` is\nadditionally omitted on any station-sourced day — see its description.\n",
      "required": [
        "date",
        "month",
        "day"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "Calendar date this slice was requested for."
        },
        "month": {
          "type": "integer",
          "description": "Month of the day-of-year slice (1-12)."
        },
        "day": {
          "type": "integer",
          "description": "Day of month (1-31)."
        },
        "normal_high": {
          "type": "number",
          "format": "double",
          "description": "Average daily maximum temperature."
        },
        "normal_low": {
          "type": "number",
          "format": "double",
          "description": "Average daily minimum temperature."
        },
        "normal_mean": {
          "type": "number",
          "format": "double",
          "description": "Average daily mean temperature."
        },
        "normal_high_stddev": {
          "type": "number",
          "format": "double",
          "description": "Standard deviation of the daily maximum. An interval, so it scales\nwithout the freezing-point offset: 3 °C of spread is 5.4 °F.\n\nAlways from the nearest station, including on a day whose\ntemperatures came from the grid — the gridded normals publish no\nstandard deviations. On such a day the temperatures describe your\npoint while this describes the named station, so read\n`station.distance_km` before narrating \"unusually warm\" off this\nspread. The same holds for `normal_low_stddev`,\n`normal_mean_stddev`, `years` and `completeness_flag`.\n"
        },
        "normal_low_stddev": {
          "type": "number",
          "format": "double",
          "description": "Standard deviation of the daily minimum. Station-sourced on the\nsame terms as `normal_high_stddev`.\n"
        },
        "normal_mean_stddev": {
          "type": "number",
          "format": "double",
          "description": "Standard deviation of the daily mean. Station-sourced on the same\nterms as `normal_high_stddev`.\n"
        },
        "normal_precip": {
          "type": "number",
          "format": "double",
          "description": "Average daily precipitation amount — inches when `unit=imperial`,\nmillimetres when `unit=metric`.\n\nThe exact inverse of `normal_high_stddev`: that is always\nstation-sourced, this is always grid-sourced. The station product\npublishes no daily precipitation normal at all, so this field comes\nonly from the gridded CONUS product and is **omitted** on any day\nwhose `source` is `station` — which includes every point outside\nCONUS. A series over Alaska or Hawaii carries temperatures with no\nprecipitation until gridded normals exist there.\n\n`0` is a real value and is not the same as omitted: a daily normal\nis a 30-year mean spread across wet and dry days, so much of the\narid West is a few hundredths of an inch. Do not treat a present\nzero as missing data.\n"
        },
        "years": {
          "type": "integer",
          "description": "Years of the base period contributing to this day, at the station.\nStation-sourced on the same terms as `normal_high_stddev`, so it\ndoes not describe the depth of a gridded value.\n"
        },
        "completeness_flag": {
          "type": "string",
          "description": "NCEI per-value completeness code, for the station. Station-sourced\non the same terms as `normal_high_stddev`.\n"
        }
      }
    },
    "ClimateNormalsMeta": {
      "type": "object",
      "description": "Provenance for a normals response.",
      "required": [
        "source",
        "unit"
      ],
      "properties": {
        "normals_period": {
          "type": "string",
          "description": "Base period the normals were computed over."
        },
        "source": {
          "type": "string",
          "description": "Where the values came from: `station` for the NCEI station\nproduct, `grid` for gridded normals, `mixed` when a series draws\non both.\n"
        },
        "normals_method": {
          "type": "string",
          "enum": [
            "official",
            "derived"
          ],
          "description": "How the normals were produced, which `source` does not answer.\n`official` means the provider publishes them as a normals product\n-- true of both the NCEI station normals and the NCEI gridded\nnormals, so a station/grid mix is still wholly official.\n`derived` means they were computed from raw climate data, which is\na weaker claim a client should qualify. Absent when upstream does\nnot report it.\n"
        },
        "unit": {
          "type": "string",
          "enum": [
            "imperial",
            "metric"
          ],
          "description": "Unit system applied to the values: °F and inches for `imperial`,\n°C and millimetres for `metric`.\n"
        },
        "approximate": {
          "type": "boolean",
          "description": "True when a station more than 50 km away supplied values that are\nactually being served — `station.distance_km` says how far.\n\nIt is not a plain distance test. A `grid` day is the requested\npoint's own normal, so no station distance makes it approximate,\nand a series whose `source` is `grid` is never flagged however far\nthe named station sits. A `mixed` series is flagged, because the\nstation-sourced days in it genuinely are approximations.\n"
        },
        "missing_days": {
          "type": "integer",
          "description": "How many days in the requested range no normal is available for,\nfrom either the grid or the station. Those days are still present\nin `days` with their temperature fields omitted.\n"
        }
      }
    },
    "ClimateNormalsStation": {
      "type": "object",
      "description": "The station a normals series was drawn from. Normals describe this\nstation, not necessarily the point you asked about.\n",
      "required": [
        "station_id",
        "latitude",
        "longitude",
        "distance_km"
      ],
      "properties": {
        "station_id": {
          "type": "string",
          "description": "GHCN station identifier."
        },
        "name": {
          "type": "string",
          "description": "Station name as published by NCEI."
        },
        "state": {
          "type": "string",
          "description": "Two-letter state or territory code."
        },
        "latitude": {
          "type": "number",
          "format": "double",
          "description": "Station latitude."
        },
        "longitude": {
          "type": "number",
          "format": "double",
          "description": "Station longitude."
        },
        "elevation_m": {
          "type": "number",
          "format": "double",
          "description": "Station elevation in metres. Worth comparing against your point:\nan elevation difference biases normals more than distance does.\n"
        },
        "distance_km": {
          "type": "number",
          "format": "double",
          "description": "Great-circle distance from the requested point to the station,\nrounded to 0.1 km. The single number that says how much to trust\nthis series.\n"
        }
      }
    },
    "Location": {
      "type": "object",
      "description": "Resolved location.",
      "required": [
        "lat",
        "lon",
        "name",
        "timezone"
      ],
      "properties": {
        "lat": {
          "type": "number",
          "format": "double",
          "minimum": -90,
          "maximum": 90
        },
        "lon": {
          "type": "number",
          "format": "double",
          "minimum": -180,
          "maximum": 180
        },
        "name": {
          "type": "string",
          "description": "Human-readable place name, usually without the state; see\n`region`. The resolved place name, else the city, else the\nnearest city. Empty when none is known.\n"
        },
        "region": {
          "type": "string",
          "description": "State or region abbreviation."
        },
        "country": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone identifier."
        },
        "county": {
          "type": "string",
          "description": "County name (US only)."
        },
        "zip": {
          "type": "string",
          "description": "ZIP code (US only)."
        }
      }
    }
  }
}