Skip to content
Vertical Weather

Get a profile

POST
/v1/atmosphere/profile
curl --request POST \
  --url https://api.verticalweather.com/v1/atmosphere/profile \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "altitude_reference": "agl", "altitudes_m": [ 1000, 2000, 5000 ], "latitude": 35.052, "longitude": -117.985, "time": "2026-09-08T12:10:00Z" }'

Returns one atmospheric profile: conditions at each requested height above the given point, at the model time nearest to time.

  • altitudes_m: 1–32 unique heights in metres; altitude_reference says whether they are above ground (agl) or above sea level (msl). Ground comes from the model terrain unless you pass ground_elevation_m_msl.
  • time: an ISO-8601 timestamp with a timezone. Compare valid_time in the response with requested_time to see which model time was actually used.
  • Winds: wind_u_ms (towards east) and wind_v_ms (towards north), plus wind_speed_ms and wind_direction_deg (degrees clockwise from true north that the wind blows from; 0 at zero speed means calm).
  • Very low heights (near 0–10 m AGL) are usually outside the pressure-level column and return 409 with the supported coverage range.

The example response was recorded from a real request. Errors use application/problem+json with a stable code. After a 429 or 503, wait for the number of seconds in Retry-After before retrying.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
altitude_reference
required
string
Allowed values: agl msl
altitudes_m
required
Array<number>
>= 1 items <= 32 items
ground_elevation_m_msl
Any of:
number
>= -1000 <= 10000
latitude
required
number
>= -90 <= 90
longitude
required
number
>= -180 <= 180
quality
string
default: best_available
Allowed values: best_available immediate
time
required
string format: date-time
Examples
Examplethree_heights_agl

Wind at 1, 2 and 5 km above ground

{
  "altitude_reference": "agl",
  "altitudes_m": [
    1000,
    2000,
    5000
  ],
  "latitude": 35.052,
  "longitude": -117.985,
  "time": "2026-09-08T12:10:00Z"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
object
altitude_reference
required
string
Allowed values: agl msl
coverage
required
object
maximum_agl_m
required
number
maximum_msl_m
required
number
minimum_agl_m
required
number
minimum_msl_m
required
number
ground_elevation_m_msl
required
number
ground_source
required
string
Allowed values: caller model
latitude
required
number
levels
required
Array<object>
object
altitude_agl_m
required
number
altitude_msl_m
required
number
density_kg_m3
required
number
> 0
pressure_pa
required
number
> 0
relative_humidity_pct
required
number
specific_humidity_kg_kg
required
number
< 1
temperature_k
required
number
> 0
wind_direction_deg
required
number
< 360
wind_speed_ms
required
number
wind_u_ms
required
number
wind_v_ms
required
number
longitude
required
number
model_ground_elevation_m_msl
required
number
provenance
required
object
attribution
string
default: Derived from NOAA/NCEP GFS model data; interpolated by this service
dataset
string
default: NOAA GFS 0.25 degree pressure levels
density_method
string
default: ideal_moist_gas_from_specific_humidity_excludes_condensate
forecast_hour
required
integer
grid_spacing_degrees
number
default: 0.25
height_convention
string
default: spherical_geometric_above_model_geoid_R6371229m
humidity_convention
string
default: relative_to_liquid_water_murphy_koop2005
is_final
boolean
licence_url
string
default: https://www.weather.gov/disclaimer
model
string
default: GFS
Allowed value: GFS
model_run_at
required
string format: date-time
processing_version
string
default: atmosphere-0.1.0
quality
required
string
Allowed values: forecast analysis
retrieved_at
required
string format: date-time
sampled_latitude
required
number
sampled_longitude
required
number
source_sha256
required
string
source_url
string
default: https://www.nco.ncep.noaa.gov/pmb/products/gfs/
spatial_interpolation
string
default: nearest_grid_point
temporal_interpolation
string
default: nearest_available_model_step
vertical_interpolation
string
default: linear_u_v_temperature_specific_humidity_log_pressure_in_geometric_height
requested_time
required
string format: date-time
supplied_ground_elevation_m_msl
required
Any of:
number
valid_time
required
string format: date-time
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"
}

4XX

Section titled “4XX”

400: Invalid request; 401: Invalid beta key; 404: Outside source coverage; 409: Outside supported vertical range; 429: Profile request rate or daily upstream-attempt limit reached. See the guide’s Errors page.

Media typeapplication/problem+json
object
code
required
string
coverage
Any of:
object
maximum_agl_m
required
number
maximum_msl_m
required
number
minimum_agl_m
required
number
minimum_msl_m
required
number
detail
Any of:
string
request_id
required
string
status
required
integer
title
required
string
type
required
string
Examplegenerated
{
  "code": "example",
  "coverage": {
    "maximum_agl_m": 1,
    "maximum_msl_m": 1,
    "minimum_agl_m": 1,
    "minimum_msl_m": 1
  },
  "detail": "example",
  "request_id": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

5XX

Section titled “5XX”

500: Internal error; 502: Unusable source column; 503: Source busy or service unavailable. See the guide’s Errors page.

Media typeapplication/problem+json
object
code
required
string
coverage
Any of:
object
maximum_agl_m
required
number
maximum_msl_m
required
number
minimum_agl_m
required
number
minimum_msl_m
required
number
detail
Any of:
string
request_id
required
string
status
required
integer
title
required
string
type
required
string
Examplegenerated
{
  "code": "example",
  "coverage": {
    "maximum_agl_m": 1,
    "maximum_msl_m": 1,
    "minimum_agl_m": 1,
    "minimum_msl_m": 1
  },
  "detail": "example",
  "request_id": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}