# Vertex API

> Weather models, observations and outdoor map layers for the continental US, for apps and agents. Open-Meteo-compatible point forecasts from 3 km HRRR/RRFS plus GFS and ECMWF, with soaring fields no other provider serves (updraft velocity, top of usable lift, cumulus base and depth, winds aloft per 1,000 ft), value-encoded weather tiles with TileJSON, radar + nowcast, lightning, stations, soundings, stream gauges, wildfire, TFRs, NWS alerts and forecast discussions, and static outdoor layers (slope, public lands, airspace, motor-vehicle-use maps, trails, peaks).

## Instructions for agents

- Base URL: https://api.vertexmaps.com. Auth: `Authorization: Bearer vtx_live_…` (or `?apikey=` for tile templates). Get a key at https://console.vertexmaps.com (free, no card).
- Every metered response carries `x-credits-cost`; add `dry_run=1` to any request to get `{product, credits}` without executing it. Read https://api.vertexmaps.com/v1/pricing.json for weights: forecast 1 (per location, per 10 hourly vars, per model), profile 3, tile 0.2, observations/overlays/text 1, catalogue/meta/usage 0.
- Free tier: 15000 credits/month and 1000/day, commercial use allowed. 402 = quota exceeded (body has `scope` and `resets_at`), 429 = burst limit (retry after 10 s).
- Point forecasts use Open-Meteo parameter names and response shape. If you already know Open-Meteo, use the same code with this base URL.
- Coverage is CONUS (lon -125..-66.5, lat 24..49.5). No history yet: `past_days`/`start_date` return 400.
- Prefer `current=` for "right now", `daily=` for day summaries, `forecast_hours=` to trim tokens. `format=csv` for tables; `format=flatbuffers` is what the Open-Meteo SDKs (openmeteo-requests etc.) request and works unchanged.
- Machine-readable contract: https://api.vertexmaps.com/v1/openapi.json

## Quick start

```
curl -H "Authorization: Bearer $VERTEX_API_KEY" \
  "https://api.vertexmaps.com/v1/forecast?latitude=46.87&longitude=-113.99&hourly=temperature_2m,wind_speed_10m,wstar,top_of_lift&daily=temperature_2m_max,wstar_max&timezone=auto&forecast_days=3"
```

## Endpoints

- https://api.vertexmaps.com/v1/forecast — hourly/current/daily point forecast; params latitude, longitude, hourly, current, daily, models, *_unit, timezone, timeformat, format, forecast_days, forecast_hours, start_hour, end_hour, elevation. Fields: 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. Daily: 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.
- https://api.vertexmaps.com/v1/profile/xsection and /v1/profile/airgram — time × altitude soaring profiles (lat, lon, model).
- https://api.vertexmaps.com/v1/layers — tile layer catalogue; https://api.vertexmaps.com/v1/layers/{model}/{var}/tilejson.json?valid=YYYY-MM-DDTHH — TileJSON for any map SDK. Tiles: https://api.vertexmaps.com/v1/tiles/{model}/{run}/{var}/f{FF}/{z}/{x}/{y}.png (value-encoded PNG; colour with the layer's stops). 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.
- Overlays: /v1/barbs/{model}/{run}/f{FF}/{level}.png (UV wind raster), /v1/isobars/…, /v1/thunder/…, /v1/precipbands/….
- Observations: /v1/radar/index.json + /v1/radar/{frame}/{z}/{x}/{y}.png, /v1/lightning/strikes.geojson, /v1/stations/latest?bbox=, /v1/stations/history, /v1/soundings/latest?bbox=, /v1/gauges/latest.geojson, /v1/gauges/{site}/history, /v1/fire/{perimeters|incidents|hotspots}.geojson, /v1/tfrs.geojson.
- Text: /v1/weather-alerts?lat=&lon=, /v1/discussions/latest, /v1/discussions/{cwa}/latest.
- Static: /v1/static/{layer}/{z}/{x}/{y}.{mvt|png} with /v1/static/{layer}/metadata; /v1/peaks/manifest.json.
- Account: /v1/usage, /v1/pricing.json (public).

## Attribution

NOAA model, radar, NWS and USGS data are public domain. ECMWF IFS data is CC BY 4.0 (attribute ECMWF, note "modified"). Trails, peaks: © OpenStreetMap contributors (ODbL). Station observations: NOAA MADIS and the named provider. Free-tier responses require "Weather by Vertex API" attribution; waived on paid plans.