Requests

A profile request is a POST to /v1/atmosphere/profile with a JSON body:

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

Field	Required	Description
latitude	yes	Decimal degrees, −90 to 90.
longitude	yes	Decimal degrees, −180 to 180.
time	yes	ISO 8601 timestamp with a timezone, such as 2026-10-03T18:00:00Z.
altitudes_m	yes	1 to 32 different heights in metres. They come back sorted.
altitude_reference	yes	agl (above ground level) or msl (above mean sea level).
ground_elevation_m_msl	no	Your own ground elevation in metres above sea level, used for agl heights.
quality	no	best_available (default) or immediate. Both currently use GFS.

Unknown fields, duplicate heights and timestamps without a timezone are rejected with a 400.

Above ground or above sea level

With agl, heights are measured from the ground under the point. By default that is the model’s own terrain height, which is smoothed over its grid cell and can differ from the real ground by tens or hundreds of metres in hilly areas. If you know the site elevation, pass it as ground_elevation_m_msl.

For example, if the ground is at 200 m above sea level, a request for 1,000 m agl is sampled at 1,200 m above sea level. The response includes both heights for every level, plus the model terrain and the ground value that was used.

Heights are geometric metres above the model’s sea-level reference. That is close to, but not the same as, a GPS altitude, which is measured from a different reference surface.

Time

GFS produces data in time steps (hourly for the first days of a forecast, then every three hours). The API uses the step nearest to your time and reports it as valid_time, next to your requested_time.

You can ask for up to 14 days ahead and about ten days back. Anything outside that range gets a 404.

Heights that aren’t available

The request accepts heights up to 30,000 m, but what’s actually available depends on the model column at that place and time. The lowest usable level is often some tens of metres above the ground, so 0 or 10 m agl usually won’t work.

If any height is outside the available column, the whole request is refused with a 409 and the response says which range is available:

{
  "code": "profile_out_of_range",
  "coverage": {
    "minimum_agl_m": 27.2,
    "maximum_agl_m": 10183.3,
    "minimum_msl_m": 780.9,
    "maximum_msl_m": 10937.1
  }
}

Adjust the heights and try again.