{
  "components": {
    "schemas": {
      "AccountInfo": {
        "properties": {
          "allowance_kind": {
            "type": "string"
          },
          "billing_enabled": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "period": {
            "type": "string"
          },
          "remaining": {
            "type": "integer"
          },
          "reset_after_seconds": {
            "type": "integer"
          },
          "upstream_attempts": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "billing_enabled",
          "allowance_kind",
          "period",
          "upstream_attempts",
          "limit",
          "remaining",
          "reset_after_seconds"
        ],
        "type": "object"
      },
      "AtmosphereLevel": {
        "properties": {
          "altitude_agl_m": {
            "type": "number"
          },
          "altitude_msl_m": {
            "type": "number"
          },
          "density_kg_m3": {
            "exclusiveMinimum": 0,
            "type": "number"
          },
          "pressure_pa": {
            "exclusiveMinimum": 0,
            "type": "number"
          },
          "relative_humidity_pct": {
            "minimum": 0,
            "type": "number"
          },
          "specific_humidity_kg_kg": {
            "exclusiveMaximum": 1,
            "minimum": 0,
            "type": "number"
          },
          "temperature_k": {
            "exclusiveMinimum": 0,
            "type": "number"
          },
          "wind_direction_deg": {
            "exclusiveMaximum": 360,
            "minimum": 0,
            "type": "number"
          },
          "wind_speed_ms": {
            "minimum": 0,
            "type": "number"
          },
          "wind_u_ms": {
            "type": "number"
          },
          "wind_v_ms": {
            "type": "number"
          }
        },
        "required": [
          "altitude_agl_m",
          "altitude_msl_m",
          "wind_u_ms",
          "wind_v_ms",
          "wind_speed_ms",
          "wind_direction_deg",
          "temperature_k",
          "pressure_pa",
          "specific_humidity_kg_kg",
          "relative_humidity_pct",
          "density_kg_m3"
        ],
        "type": "object"
      },
      "AtmosphereProblem": {
        "properties": {
          "code": {
            "type": "string"
          },
          "coverage": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/VerticalCoverage"
              },
              {
                "type": "null"
              }
            ]
          },
          "detail": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "request_id": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "code",
          "request_id"
        ],
        "type": "object"
      },
      "AtmosphereProvenance": {
        "properties": {
          "attribution": {
            "default": "Derived from NOAA/NCEP GFS model data; interpolated by this service",
            "type": "string"
          },
          "dataset": {
            "default": "NOAA GFS 0.25 degree pressure levels",
            "type": "string"
          },
          "density_method": {
            "default": "ideal_moist_gas_from_specific_humidity_excludes_condensate",
            "type": "string"
          },
          "forecast_hour": {
            "minimum": 0,
            "type": "integer"
          },
          "grid_spacing_degrees": {
            "default": 0.25,
            "type": "number"
          },
          "height_convention": {
            "default": "spherical_geometric_above_model_geoid_R6371229m",
            "type": "string"
          },
          "humidity_convention": {
            "default": "relative_to_liquid_water_murphy_koop2005",
            "type": "string"
          },
          "is_final": {
            "const": false,
            "default": false,
            "type": "boolean"
          },
          "licence_url": {
            "default": "https://www.weather.gov/disclaimer",
            "type": "string"
          },
          "model": {
            "const": "GFS",
            "default": "GFS",
            "type": "string"
          },
          "model_run_at": {
            "format": "date-time",
            "type": "string"
          },
          "processing_version": {
            "default": "atmosphere-0.1.0",
            "type": "string"
          },
          "quality": {
            "enum": [
              "forecast",
              "analysis"
            ],
            "type": "string"
          },
          "retrieved_at": {
            "format": "date-time",
            "type": "string"
          },
          "sampled_latitude": {
            "type": "number"
          },
          "sampled_longitude": {
            "type": "number"
          },
          "source_sha256": {
            "type": "string"
          },
          "source_url": {
            "default": "https://www.nco.ncep.noaa.gov/pmb/products/gfs/",
            "type": "string"
          },
          "spatial_interpolation": {
            "default": "nearest_grid_point",
            "type": "string"
          },
          "temporal_interpolation": {
            "default": "nearest_available_model_step",
            "type": "string"
          },
          "vertical_interpolation": {
            "default": "linear_u_v_temperature_specific_humidity_log_pressure_in_geometric_height",
            "type": "string"
          }
        },
        "required": [
          "model_run_at",
          "forecast_hour",
          "quality",
          "retrieved_at",
          "sampled_latitude",
          "sampled_longitude",
          "source_sha256"
        ],
        "type": "object"
      },
      "AtmosphereRequest": {
        "additionalProperties": false,
        "properties": {
          "altitude_reference": {
            "enum": [
              "agl",
              "msl"
            ],
            "type": "string"
          },
          "altitudes_m": {
            "items": {
              "type": "number"
            },
            "maxItems": 32,
            "minItems": 1,
            "type": "array"
          },
          "ground_elevation_m_msl": {
            "anyOf": [
              {
                "maximum": 10000,
                "minimum": -1000,
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "latitude": {
            "maximum": 90,
            "minimum": -90,
            "type": "number"
          },
          "longitude": {
            "maximum": 180,
            "minimum": -180,
            "type": "number"
          },
          "quality": {
            "default": "best_available",
            "enum": [
              "best_available",
              "immediate"
            ],
            "type": "string"
          },
          "time": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "latitude",
          "longitude",
          "time",
          "altitudes_m",
          "altitude_reference"
        ],
        "type": "object"
      },
      "AtmosphereResponse": {
        "properties": {
          "altitude_reference": {
            "enum": [
              "agl",
              "msl"
            ],
            "type": "string"
          },
          "coverage": {
            "$ref": "#/components/schemas/VerticalCoverage"
          },
          "ground_elevation_m_msl": {
            "type": "number"
          },
          "ground_source": {
            "enum": [
              "caller",
              "model"
            ],
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "levels": {
            "items": {
              "$ref": "#/components/schemas/AtmosphereLevel"
            },
            "type": "array"
          },
          "longitude": {
            "type": "number"
          },
          "model_ground_elevation_m_msl": {
            "type": "number"
          },
          "provenance": {
            "$ref": "#/components/schemas/AtmosphereProvenance"
          },
          "requested_time": {
            "format": "date-time",
            "type": "string"
          },
          "supplied_ground_elevation_m_msl": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "valid_time": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "latitude",
          "longitude",
          "requested_time",
          "valid_time",
          "altitude_reference",
          "ground_elevation_m_msl",
          "model_ground_elevation_m_msl",
          "supplied_ground_elevation_m_msl",
          "ground_source",
          "coverage",
          "levels",
          "provenance"
        ],
        "type": "object"
      },
      "BetaUsage": {
        "properties": {
          "billing_enabled": {
            "const": false,
            "default": false,
            "type": "boolean"
          },
          "limit": {
            "type": "integer"
          },
          "period": {
            "const": "utc_day",
            "default": "utc_day",
            "type": "string"
          },
          "remaining": {
            "minimum": 0,
            "type": "integer"
          },
          "reset_after_seconds": {
            "minimum": 1,
            "type": "integer"
          },
          "upstream_attempts": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "upstream_attempts",
          "limit",
          "remaining",
          "reset_after_seconds"
        ],
        "type": "object"
      },
      "CreatedKey": {
        "properties": {
          "id": {
            "type": "string"
          },
          "key": {
            "description": "Shown once. Store securely; never embed in a browser app.",
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "key",
          "name"
        ],
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "KeyInfo": {
        "properties": {
          "created_at": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "revoked_at": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "prefix",
          "name",
          "created_at",
          "revoked_at"
        ],
        "type": "object"
      },
      "KeyList": {
        "properties": {
          "keys": {
            "items": {
              "$ref": "#/components/schemas/KeyInfo"
            },
            "type": "array"
          }
        },
        "required": [
          "keys"
        ],
        "type": "object"
      },
      "NewKey": {
        "additionalProperties": false,
        "properties": {
          "name": {
            "maxLength": 80,
            "minLength": 1,
            "pattern": "^[^\\x00-\\x1f\\x7f]+$",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "type": "object"
          },
          "input": {},
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "type": "object"
      },
      "VerticalCoverage": {
        "properties": {
          "maximum_agl_m": {
            "type": "number"
          },
          "maximum_msl_m": {
            "type": "number"
          },
          "minimum_agl_m": {
            "type": "number"
          },
          "minimum_msl_m": {
            "type": "number"
          }
        },
        "required": [
          "minimum_msl_m",
          "maximum_msl_m",
          "minimum_agl_m",
          "maximum_agl_m"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "APIKeyHeader": {
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "Wind, temperature, pressure, humidity and air density at the heights you choose\nabove a point, from NOAA's GFS model. Guides: https://verticalweather.com\n\nSend heights in metres above ground (`agl`) or above sea level (`msl`) to\n`POST /v1/atmosphere/profile`, with your key in the `X-API-Key` header.\n",
    "summary": "Wind, temperature and air density at any height above a location, from NOAA GFS.",
    "title": "Vertical Weather API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/atmosphere/profile": {
      "post": {
        "description": "Returns one atmospheric profile: conditions at each requested height above the\ngiven point, at the model time nearest to `time`.\n\n- `altitudes_m`: 1–32 unique heights in metres; `altitude_reference` says whether\n  they are above ground (`agl`) or above sea level (`msl`). Ground comes from the\n  model terrain unless you pass `ground_elevation_m_msl`.\n- `time`: an ISO-8601 timestamp with a timezone. Compare `valid_time` in the\n  response with `requested_time` to see which model time was actually used.\n- Winds: `wind_u_ms` (towards east) and `wind_v_ms` (towards north), plus\n  `wind_speed_ms` and `wind_direction_deg` (degrees clockwise from true north that\n  the wind blows *from*; 0 at zero speed means calm).\n- Very low heights (near 0–10 m AGL) are usually outside the pressure-level column\n  and return `409` with the supported `coverage` range.\n\nThe example response was recorded from a real request. Errors use\n`application/problem+json` with a stable `code`. After a `429` or `503`, wait for\nthe number of seconds in `Retry-After` before retrying.",
        "operationId": "get_atmospheric_profile",
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "three_heights_agl": {
                  "summary": "Wind at 1, 2 and 5 km above ground",
                  "value": {
                    "altitude_reference": "agl",
                    "altitudes_m": [
                      1000,
                      2000,
                      5000
                    ],
                    "latitude": 35.052,
                    "longitude": -117.985,
                    "time": "2026-09-08T12:10:00Z"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/AtmosphereRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "altitude_reference": "agl",
                  "coverage": {
                    "maximum_agl_m": 10183.345570458954,
                    "maximum_msl_m": 10937.094107165602,
                    "minimum_agl_m": 27.187922772751676,
                    "minimum_msl_m": 780.9364594793992
                  },
                  "ground_elevation_m_msl": 753.7485367066475,
                  "ground_source": "model",
                  "latitude": 35.052,
                  "levels": [
                    {
                      "altitude_agl_m": 1000,
                      "altitude_msl_m": 1753.7485367066474,
                      "density_kg_m3": 0.9763716831689078,
                      "pressure_pa": 82734.3208847534,
                      "relative_humidity_pct": 46.9711339410645,
                      "specific_humidity_kg_kg": 0.008574039134040905,
                      "temperature_k": 293.66748393309285,
                      "wind_direction_deg": 253.12155120805502,
                      "wind_speed_ms": 3.8450224873865375,
                      "wind_u_ms": 3.679389919079603,
                      "wind_v_ms": 1.1163725864976923
                    },
                    {
                      "altitude_agl_m": 2000,
                      "altitude_msl_m": 2753.7485367066474,
                      "density_kg_m3": 0.8895118757482096,
                      "pressure_pa": 73573.0119450468,
                      "relative_humidity_pct": 56.23324861986829,
                      "specific_humidity_kg_kg": 0.007483832526248116,
                      "temperature_k": 286.8391740852655,
                      "wind_direction_deg": 240.75021355187897,
                      "wind_speed_ms": 6.402867182808112,
                      "wind_u_ms": 5.586487711558693,
                      "wind_v_ms": 3.1285560901612124
                    },
                    {
                      "altitude_agl_m": 5000,
                      "altitude_msl_m": 5753.748536706647,
                      "density_kg_m3": 0.6650933474527685,
                      "pressure_pa": 50856.29755967961,
                      "relative_humidity_pct": 56.248480717752,
                      "specific_humidity_kg_kg": 0.0024623300051281392,
                      "temperature_k": 265.9837924670181,
                      "wind_direction_deg": 225.17628889449685,
                      "wind_speed_ms": 11.87809858743052,
                      "wind_u_ms": 8.424886745294033,
                      "wind_v_ms": 8.373201859604713
                    }
                  ],
                  "longitude": -117.985,
                  "model_ground_elevation_m_msl": 753.7485367066475,
                  "provenance": {
                    "attribution": "Derived from NOAA/NCEP GFS model data; interpolated by this service",
                    "dataset": "NOAA GFS 0.25 degree pressure levels",
                    "density_method": "ideal_moist_gas_from_specific_humidity_excludes_condensate",
                    "forecast_hour": 12,
                    "grid_spacing_degrees": 0.25,
                    "height_convention": "spherical_geometric_above_model_geoid_R6371229m",
                    "humidity_convention": "relative_to_liquid_water_murphy_koop2005",
                    "is_final": false,
                    "licence_url": "https://www.weather.gov/disclaimer",
                    "model": "GFS",
                    "model_run_at": "2026-09-08T00:00:00Z",
                    "processing_version": "atmosphere-0.1.0",
                    "quality": "forecast",
                    "retrieved_at": "2026-09-13T03:09:27.174917Z",
                    "sampled_latitude": 35,
                    "sampled_longitude": -118,
                    "source_sha256": "c8d49bd89754f422a25933701f712ef8a830a062d50c8d28c92acaaed30b1a87",
                    "source_url": "https://www.nco.ncep.noaa.gov/pmb/products/gfs/",
                    "spatial_interpolation": "nearest_grid_point",
                    "temporal_interpolation": "nearest_available_model_step",
                    "vertical_interpolation": "linear_u_v_temperature_specific_humidity_log_pressure_in_geometric_height"
                  },
                  "requested_time": "2026-09-08T12:10:00Z",
                  "supplied_ground_elevation_m_msl": null,
                  "valid_time": "2026-09-08T12:00:00Z"
                },
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Invalid request"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Invalid beta key"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Outside source coverage"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Outside supported vertical range"
          },
          "429": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Profile request rate or daily upstream-attempt limit reached"
          },
          "500": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Internal error"
          },
          "502": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Unusable source column"
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Source busy or service unavailable"
          }
        },
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "summary": "Get a profile"
      }
    },
    "/v1/atmosphere/capabilities": {
      "get": {
        "description": "Configured coverage, returned fields and usage limits. No API key needed.",
        "operationId": "capabilities_v1_atmosphere_capabilities_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Get capabilities"
      }
    },
    "/v1/atmosphere/usage": {
      "get": {
        "description": "Today's data-fetch count and remaining allowance for your account (UTC day).",
        "operationId": "usage_v1_atmosphere_usage_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BetaUsage"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Unauthorized"
          },
          "503": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/AtmosphereProblem"
                }
              }
            },
            "description": "Service Unavailable"
          }
        },
        "security": [
          {
            "APIKeyHeader": []
          }
        ],
        "summary": "Get usage"
      }
    }
  },
  "servers": [
    {
      "url": "https://api.verticalweather.com",
      "description": "Vertical Weather API"
    }
  ]
}