{"openapi":"3.1.0","info":{"title":"Vertex API","version":"1.0.0","summary":"Weather models, observations and outdoor layers for CONUS, priced in credits.","description":"Open-Meteo-compatible point forecasts (HRRR/RRFS 3 km, GFS, ECMWF) with soaring-specific derived fields, value-encoded weather tiles + TileJSON, radar/lightning/stations/soundings/gauges/fire/TFR observations, NWS text products, and static outdoor layers. Every response carries x-credits-cost; add dry_run=1 to price a request first. Free: 15000 credits/month (1000/day), commercial use allowed. Pay-as-you-go from $0.5 per 1,000 credits. See /v1/pricing.json.","contact":{"url":"https://vertexmaps.com","email":"hello@vertexmaps.com"},"x-llms-txt":"https://api.vertexmaps.com/llms.txt"},"servers":[{"url":"https://api.vertexmaps.com"}],"security":[{"bearer":[]},{"apikey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer vtx_live_…"},"apikey":{"type":"apiKey","in":"query","name":"apikey","description":"for map-SDK tile templates"}},"headers":{"x-credits-cost":{"description":"credits this request consumed (0 on 4xx/5xx)","schema":{"type":"number"}},"x-credits-remaining":{"description":"credits left this month (free tier)","schema":{"type":"number"}},"x-credits-daily-remaining":{"description":"credits left today (free tier)","schema":{"type":"number"}},"x-spend-remaining-usd":{"description":"USD left before the spend cap (pay-as-you-go)","schema":{"type":"number"}},"ratelimit-limit":{"description":"requests allowed per 10 s window","schema":{"type":"integer"}}},"responses":{"401":{"description":"missing or invalid API key"},"402":{"description":"quota exceeded (daily, monthly or spend cap); body has scope + resets_at"},"429":{"description":"burst limit; retry after 10 s"}}},"x-pricing":{"unit":"credit","weights":{"forecast":1,"current":0.5,"profile":3,"tile":0.2,"overlay":1,"observations":1,"text":1,"places":1,"render":10,"catalog":0,"other":1},"forecast":"locations × ceil(hourly vars / 10) × models","free":{"monthly_credits":15000,"daily_credits":1000,"requests_per_10s":100,"keys":1,"commercial_use":true,"attribution_required":true},"payg_usd_per_1k":[{"up_to":1000000,"usd_per_1k":0.5},{"up_to":5000000,"usd_per_1k":0.35},{"up_to":null,"usd_per_1k":0.25}],"url":"https://api.vertexmaps.com/v1/pricing.json"},"tags":[{"name":"forecast"},{"name":"profiles"},{"name":"tiles"},{"name":"overlays"},{"name":"observations"},{"name":"text"},{"name":"static"},{"name":"account"}],"paths":{"/v1/forecast":{"get":{"summary":"Point forecast (Open-Meteo compatible)","description":"Hourly, current and daily values at one or more locations. Same parameter names and response shape as Open-Meteo's /v1/forecast, plus Vertex fields (wstar, top_of_lift, cloud_base, cu_depth, winds aloft per 1000 ft, smoke). Several models → fields suffixed _model on a shared time axis. Alias: /v1/point. History parameters are rejected (400) until the archive-backed history ships.","tags":["forecast"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"latitude","in":"query","description":"comma list, WGS84","required":true,"schema":{"type":"string"}},{"name":"longitude","in":"query","description":"comma list, same length","required":true,"schema":{"type":"string"}},{"name":"hourly","in":"query","description":"comma list of: temperature_2m, dew_point_2m, relative_humidity_2m, cloud_cover, cloud_cover_low, cloud_cover_mid, cloud_cover_high, precipitation, wind_speed_10m, wind_direction_10m, wind_gusts_10m, cape, surface_pressure, pressure_msl, boundary_layer_height, wstar, hcrit, top_of_lift, top_of_lift_agl, cloud_base, cloud_base_agl, cu_depth, snowfall, snowfall_water_equivalent, snow_depth, snow_water_equivalent, smoke, us_aqi, wind_speed_{1000..18000}ft, wind_direction_{1000..18000}ft","required":false,"schema":{"type":"string"}},{"name":"current","in":"query","description":"comma list of hourly field names; value at the current hour","required":false,"schema":{"type":"string"}},{"name":"daily","in":"query","description":"comma list of: temperature_2m_max, temperature_2m_min, precipitation_sum, snowfall_sum, wind_speed_10m_max, wind_gusts_10m_max, cloud_cover_mean, relative_humidity_2m_mean, cape_max, wstar_max, top_of_lift_max, cloud_base_min, smoke_max, us_aqi_max","required":false,"schema":{"type":"string"}},{"name":"models","in":"query","description":"comma list of hrrr|rrfs|gfs|ecmwf|nam (default hrrr; Open-Meteo slugs accepted)","required":false,"schema":{"type":"string"}},{"name":"temperature_unit","in":"query","description":"celsius | fahrenheit","required":false,"schema":{"type":"string"}},{"name":"wind_speed_unit","in":"query","description":"kmh | ms | mph | kn","required":false,"schema":{"type":"string"}},{"name":"precipitation_unit","in":"query","description":"mm | inch (also drives snowfall/snow_depth)","required":false,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"IANA name, GMT, or auto (CONUS approximation)","required":false,"schema":{"type":"string"}},{"name":"timeformat","in":"query","description":"iso8601 | unixtime","required":false,"schema":{"type":"string"}},{"name":"format","in":"query","description":"json | csv | flatbuffers (the Open-Meteo SDK binary)","required":false,"schema":{"type":"string"}},{"name":"forecast_days","in":"query","description":"1-16, counted from today in the response timezone","required":false,"schema":{"type":"integer"}},{"name":"forecast_hours","in":"query","description":"1-384, counted from the current hour","required":false,"schema":{"type":"integer"}},{"name":"start_hour","in":"query","description":"YYYY-MM-DDTHH:MM in the response timezone","required":false,"schema":{"type":"string"}},{"name":"end_hour","in":"query","description":"YYYY-MM-DDTHH:MM in the response timezone","required":false,"schema":{"type":"string"}},{"name":"elevation","in":"query","description":"metres; overrides the 90 m DEM for the lapse-rate correction","required":false,"schema":{"type":"number"}},{"name":"dry_run","in":"query","description":"1 → return {product, credits} without executing","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"one object, or an array when several locations were given","content":{"application/json":{"example":{"latitude":46.87,"longitude":-113.99,"elevation":980,"model":"hrrr","model_run":"2026-09-19T00:00Z","model_elevation":1204,"utc_offset_seconds":-21600,"timezone":"America/Denver","timezone_abbreviation":"MDT","hourly_units":{"time":"iso8601","temperature_2m":"°C","wstar":"m/s","top_of_lift":"m"},"hourly":{"time":["2026-09-18T18:00"],"temperature_2m":[23.1],"wstar":[2.4],"top_of_lift":[3820]}}}}},"400":{"description":"bad parameter, unknown field, field not available for the model, location outside CONUS"},"401":{"$ref":"#/components/responses/401"},"402":{"$ref":"#/components/responses/402"},"429":{"$ref":"#/components/responses/429"},"503":{"description":"model has no published store yet"}}}},"/v1/profile/xsection":{"get":{"summary":"Time × altitude soaring cross-section","description":"Winds aloft, Lenschow updraft profile, top of lift, cloud base, LCL, cu top, boundary-layer top and a surface strip for one location. Alias: /v1/xsection. 3 credits.","tags":["profiles"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"lat","in":"query","description":"","required":true,"schema":{"type":"number"}},{"name":"lon","in":"query","description":"","required":true,"schema":{"type":"number"}},{"name":"model","in":"query","description":"hrrr|rrfs|gfs|ecmwf|nam","required":false,"schema":{"type":"string"}},{"name":"wind_speed_unit","in":"query","description":"ms | kmh | mph | kn (default ms)","required":false,"schema":{"type":"string"}},{"name":"timezone","in":"query","description":"IANA or auto","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"grid[t][level] arrays + surface series","content":{"application/json":{}}}}}},"/v1/profile/airgram":{"get":{"summary":"RH/wind profile to 40,000 ft (airgram)","description":"rh[t][level], winds, freezing level, cloud base and cu top. hrrr, rrfs and gfs only. Alias: /v1/airgram. 3 credits.","tags":["profiles"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"lat","in":"query","description":"","required":true,"schema":{"type":"number"}},{"name":"lon","in":"query","description":"","required":true,"schema":{"type":"number"}},{"name":"model","in":"query","description":"hrrr|rrfs|gfs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"profile","content":{"application/json":{}}}}}},"/v1/layers":{"get":{"summary":"Layer catalogue","description":"Every (model, var) tile layer with its run, published valid hours, zoom ceiling, encode range and colour stops. Free.","tags":["tiles"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"catalogue","content":{"application/json":{}}}}}},"/v1/layers/{model}/{var}/tilejson.json":{"get":{"summary":"TileJSON for one layer at one valid hour","description":"TileJSON 3.0 with the run-stamped XYZ template (current or retained extended run resolved for you). Free. Works as a source in MapLibre, Mapbox, Leaflet, deck.gl, QGIS.","tags":["tiles"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"model","in":"path","required":true,"schema":{"type":"string","enum":["hrrr","rrfs","gfs","ecmwf","nam"]}},{"name":"var","in":"path","required":true,"schema":{"type":"string","enum":["temp","cloud","cloudlow","cloudmid","cloudhigh","clouddecks","precip1h","precip3h","snow6h","snow12h","snow24h","snow48h","snowdepth","windspeed","gust","wstar","cubase","toplift","cudepth","spreadout","odpot","cape","conv","smoke","aqi","refl"]}},{"name":"valid","in":"query","description":"YYYY-MM-DDTHH (UTC)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TileJSON","content":{"application/json":{}}},"404":{"description":"not published for that hour"}}}},"/v1/tiles/{model}/{run}/{var}/f{FF}/{z}/{x}/{y}.png":{"get":{"summary":"Weather tile (value-encoded PNG)","description":"R=G=B=(v-lo)/(hi-lo)*254, alpha 0 = nodata; colour client-side from the layer's stops. Run-stamped, immutable, cache forever. Vars: temp, cloud, cloudlow, cloudmid, cloudhigh, clouddecks, precip1h, precip3h, snow6h, snow12h, snow24h, snow48h, snowdepth, windspeed, gust, wstar, cubase, toplift, cudepth, spreadout, odpot, cape, conv, smoke, aqi, refl. 0.2 credits.","security":[{"bearer":[]},{"apikey":[]}],"tags":["tiles"],"parameters":[{"name":"z","in":"path","required":true,"schema":{"type":"integer"}},{"name":"x","in":"path","required":true,"schema":{"type":"integer"}},{"name":"y","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"PNG tile","content":{"image/png":{}}},"204":{"description":"empty tile"}}}},"/v1/radar/index.json":{"get":{"summary":"Radar frame list","description":"MRMS reflectivity frames for the trailing 2 h at 5-min steps plus nowcast to +60 min. Free.","tags":["observations"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"{frames:[{time,name,kind}]}"}}}},"/v1/radar/{frame}/{z}/{x}/{y}.png":{"get":{"summary":"Radar tile","description":"MRMS composite reflectivity, value-encoded like weather tiles; frames are immutable.","security":[{"bearer":[]},{"apikey":[]}],"tags":["tiles"],"parameters":[{"name":"z","in":"path","required":true,"schema":{"type":"integer"}},{"name":"x","in":"path","required":true,"schema":{"type":"integer"}},{"name":"y","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"PNG tile","content":{"image/png":{}}},"204":{"description":"empty tile"}}}},"/v1/barbs/{model}/{run}/f{FF}/{level}.png":{"get":{"summary":"Wind field raster (UV-encoded PNG)","description":"Levels: sfc and 1000..18000ft. Encoding lo/hi ±60 m/s over meta.barbs[model].field.bbox. 1 credit.","tags":["overlays"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"PNG"}}}},"/v1/isobars/{model}/{run}/f{FF}.geojson":{"get":{"summary":"MSLP isobars","description":"Contour lines, run-stamped.","security":[{"bearer":[]},{"apikey":[]}],"tags":["overlays"],"responses":{"200":{"description":"GeoJSON (gzip)","content":{"application/geo+json":{}}}}}},"/v1/thunder/{model}/{run}/f{FF}.geojson":{"get":{"summary":"Forecast lightning potential","description":"Bolt points with tiers from HRRR LTNG (forecast, not observed strikes).","security":[{"bearer":[]},{"apikey":[]}],"tags":["overlays"],"responses":{"200":{"description":"GeoJSON (gzip)","content":{"application/geo+json":{}}}}}},"/v1/precipbands/{model}/{run}/{var}/f{FF}.geojson":{"get":{"summary":"Banded precipitation polygons","description":"var: precip1h | precip3h.","security":[{"bearer":[]},{"apikey":[]}],"tags":["overlays"],"responses":{"200":{"description":"GeoJSON (gzip)","content":{"application/geo+json":{}}}}}},"/v1/stations/latest":{"get":{"summary":"Latest surface observations","description":"MADIS category-3 stations in a bbox (≤16 z5 tiles). vars: t,dp,rh,ws,wd,wg,pa,p,p1h,sr,sd,sf6,sf24,swe,stage,flow. SI units. Attribution: provider names + NOAA MADIS.","tags":["observations"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"bbox","in":"query","description":"w,s,e,n","required":true,"schema":{"type":"string"}},{"name":"vars","in":"query","description":"comma list","required":false,"schema":{"type":"string"}},{"name":"within","in":"query","description":"minutes, default 120, max 1440","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"GeoJSON FeatureCollection"}}}},"/v1/stations/history":{"get":{"summary":"One station's history (7 days)","tags":["observations"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"provider","in":"query","description":"","required":true,"schema":{}},{"name":"id","in":"query","description":"","required":true,"schema":{}},{"name":"lat","in":"query","description":"","required":true,"schema":{"type":"number"}},{"name":"lon","in":"query","description":"","required":true,"schema":{"type":"number"}},{"name":"vars","in":"query","description":"","required":false,"schema":{"type":"string"}},{"name":"hours","in":"query","description":"≤168","required":false,"schema":{"type":"integer"}},{"name":"cadence","in":"query","description":"native for raw reports","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"series"}}}},"/v1/lightning/strikes.geojson":{"get":{"summary":"Observed lightning (trailing 2 h)","description":"MRMS NLDN cloud-to-ground density cells, rewritten every minute.","security":[{"bearer":[]},{"apikey":[]}],"tags":["observations"],"responses":{"200":{"description":"GeoJSON (gzip)","content":{"application/geo+json":{}}}}}},"/v1/soundings/latest":{"get":{"summary":"Radiosonde launch sites with latest report","tags":["observations"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"bbox","in":"query","description":"w,s,e,n","required":true,"schema":{"type":"string"}},{"name":"within","in":"query","description":"hours, default 24","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"GeoJSON"}}}},"/v1/soundings/stations/{wmo}":{"get":{"summary":"One site's reports (7 days)","tags":["observations"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"{reports:[…]}"}}}},"/v1/gauges/latest.geojson":{"get":{"summary":"USGS stream gauges nationwide","description":"Discharge, stage, water temperature and a rating fit per site; every 15 min.","security":[{"bearer":[]},{"apikey":[]}],"tags":["observations"],"responses":{"200":{"description":"GeoJSON (gzip)","content":{"application/geo+json":{}}}}}},"/v1/gauges/{site}/history":{"get":{"summary":"One gauge's recent series (NWIS proxy)","tags":["observations"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"parameterCd","in":"query","description":"default 00060","required":false,"schema":{"type":"string"}},{"name":"period","in":"query","description":"P7D","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"WaterML JSON"}}}},"/v1/fire/{perimeters|incidents|hotspots}.geojson":{"get":{"summary":"Wildfire perimeters, incidents, VIIRS hotspots (48 h)","description":"NIFC WFIGS + NASA FIRMS; hourly.","security":[{"bearer":[]},{"apikey":[]}],"tags":["observations"],"responses":{"200":{"description":"GeoJSON (gzip)","content":{"application/geo+json":{}}}}}},"/v1/tfrs.geojson":{"get":{"summary":"Active FAA TFRs","description":"Every 15 min.","security":[{"bearer":[]},{"apikey":[]}],"tags":["observations"],"responses":{"200":{"description":"GeoJSON (gzip)","content":{"application/geo+json":{}}}}}},"/v1/weather-alerts":{"get":{"summary":"Active NWS alerts at a point","tags":["text"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"lat","in":"query","description":"","required":true,"schema":{"type":"number"}},{"name":"lon","in":"query","description":"","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"{alerts:[NWS features]}"}}}},"/v1/discussions/latest":{"get":{"summary":"NWS Area Forecast Discussions, latest per office","tags":["text"],"security":[{"bearer":[]},{"apikey":[]}],"parameters":[{"name":"bbox","in":"query","description":"w,s,e,n","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"areas with freshness + documentUrl"}}}},"/v1/discussions/{cwa}/latest":{"get":{"summary":"One office's current AFD, verbatim, sectioned","tags":["text"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"document"}}}},"/v1/static/{layer}/{z}/{x}/{y}.{mvt|png}":{"get":{"summary":"Static outdoor layer tile","description":"PMTiles-backed. Layers: slope-conus (PNG, value = degrees), terrain-conus, lands-conus (MVT: fee/designation/easement/tribal/bma/military), airspace-us (MVT: class/modec/sua), mvum-conus, trails-mt (MVT, ODbL). See /v1/static/{layer}/metadata.","security":[{"bearer":[]},{"apikey":[]}],"tags":["tiles"],"parameters":[{"name":"z","in":"path","required":true,"schema":{"type":"integer"}},{"name":"x","in":"path","required":true,"schema":{"type":"integer"}},{"name":"y","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"PNG tile","content":{"image/png":{}}},"204":{"description":"empty tile"}}}},"/v1/static/{layer}/metadata":{"get":{"summary":"Static layer metadata (bounds, zooms, format, attribution)","tags":["static"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"metadata"}}}},"/v1/peaks/manifest.json":{"get":{"summary":"Named peaks catalogue (CONUS, OSM/ODbL)","tags":["static"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"manifest with cell URLs"}}}},"/v1/meta.json":{"get":{"summary":"Model runs, valid hours, layer encodings and colour stops","description":"The discovery document behind /v1/layers. Free.","tags":["tiles"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"meta"}}}},"/v1/usage":{"get":{"summary":"This key's credit counters and caps","tags":["account"],"security":[{"bearer":[]},{"apikey":[]}],"responses":{"200":{"description":"usage"}}}},"/v1/pricing.json":{"get":{"summary":"Machine-readable price list (no key needed)","tags":["account"],"security":[],"responses":{"200":{"description":"pricing"}}}}}}