Sugra Earth: the physical world as an API

Series: Sugra product directions (6 of 7)
Audience: developers integrating the Sugra API over HTTP
Live samples verified: 2026-07-24 against https://sugra.ai
Auth: x-api-key header on every data call

Standalone article. Sugra Earth covers weather and climate, hazards, air quality, energy systems, and transport infrastructure that moves through the physical world.

Essence

The physical world as an API - weather, climate, disasters, energy, satellite - and the infrastructure that moves through it.

Upstreams are sovereign, intergovernmental, or academic: NOAA, USGS, NASA, ECMWF, EUMETSAT, Copernicus, EIA, ENTSO-E, Open-Meteo, and peers. Sources are named in meta.source and, on v2 surfaces, in per-field provenance plus machine-readable attribution (license and citation).

What this direction is not

Not this	Why
Consumer weather app	API for systems and agents
Official warning authority	Forecasts and retransmitted hazards - see disclaimers
Imagery hosting CDN	Satellite layers are references, not a media host
Network IP intelligence	Sugra NetAtlas
Market commodities trading desk	Some commodities live under Finance; grid is Earth

Capability map

Category	Endpoints (approx.)	Coverage
Environment	142	Multi-model weather spine, NWS, climate, marine, tides, quakes/volcanoes/fires/space weather, Climate TRACE, NASA GIBS
Transportation	14	METAR/TAF/SIGMET, tides, waves, vessel density, port activity
Energy	12	Grid demand/fuel mix (US, GB, DK, EU zones, AU), solar radiation, PV/wind potential, tariffs, OSM power assets
Disasters and Hazards	8	Unified `/api/v2/hazards/*` schema
Air Quality	1+	Point AQ: TROPOMI + CAMS layers

Family badges often show 140+. Live OpenAPI wins for exact counts.

Path note (live): aviation METAR is under /api/v2/transport/aviation/metar?ids=KJFK, not /api/v1/aviation/metar.

Why the response shape is useful

1. Multi-model weather with per-field provenance

Live Berlin point weather (lat=52.52&lon=13.405, 2026-07-24, truncated):

{
  "data": {
    "location": {
      "requested": { "lat": 52.52, "lon": 13.405 },
      "grid_point": { "lat": 52.5, "lon": 13.5 }
    },
    "weather": {
      "temperature_c": 13.97,
      "wind_speed_ms": 3.64,
      "pressure_hpa": 1017.66,
      "relative_humidity_pct": 81.1,
      "cloud_cover_pct": 45.3,
      "precipitation_mm": 0.0
    },
    "forecast": { "name": "ECMWF Open Data (IFS)", "cycle": "2026072400" },
    "provenance": {
      "temperature": { "institution": "ecmwf", "model": "ifs-open" },
      "gust": { "institution": "noaa", "model": "gfs" },
      "precipitation": { "institution": "openmeteo", "model": "best_match" }
    },
    "attribution": {
      "sources": [
        { "source_name": "ECMWF Open Data (IFS)", "licence": "CC-BY-4.0" },
        { "source_name": "NOAA GFS", "licence": "public-domain" }
      ]
    }
  },
  "meta": {
    "source": "ecmwf_ifs_open",
    "fallback_chain": ["ecmwf_ifs_open", "noaa_gfs"]
  }
}

Agents can cite institution + license per field.

2. Unified hazard event schema

Live earthquakes (day window, min magnitude 4.5): 19 matched; events include geometry, metrics, severity block, USGS source URL, and disclaimer that magnitudes are preliminary.

Same schema family for other hazard types under /api/v2/hazards/*.

3. Grid operating series

Live US48 demand: region name, metric unit megawatthours, hourly points, meta.source e.g. eia.

4. Air quality multi-product merge

Satellite columns and surface model layers reported separately with their own timestamps.

Developer path

export SUGRA_API_KEY="YOUR_API_KEY"

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/weather?lat=52.52&lon=13.405"

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/hazards/earthquakes?window=day&min_magnitude=4.5&limit=5"

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/energy/grid?region=US48&metric=demand&limit=24"

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/transport/aviation/metar?ids=KJFK"

Use case 1: Point weather for operations

Goal. Conditions at a lat/lon for logistics, field ops, or agents.

Calls. /api/v2/weather, /weather/forecast, /weather/history.

Strength. Best-match multi-model + provenance.
Pitfalls. Grid resolution (0.25 deg class); not a warning product.

Use case 2: Active hazards desk

Goal. Recent earthquakes (or other hazards) above a threshold.

Call. /api/v2/hazards/earthquakes?window=day&min_magnitude=4.5.

Strength. Normalized event objects + USGS citation.
Pitfalls. Preliminary magnitudes; always show disclaimer.

Use case 3: Grid load monitor

Goal. Track demand / generation / fuel mix for a region.

Call. /api/v2/energy/grid?region=US48&metric=demand.

Strength. Cross-region energy surface under one key.
Pitfalls. Region codes and metric enums matter; check docs for available regions.

Portal recipe: grid-load-monitor.md.

Use case 4: Air quality at a point

Goal. Satellite + model AQ snapshot for a city coordinate.

Call. /api/v2/air-quality?lat=&lon=.

Strength. Layered products with separate timestamps.
Pitfalls. Units differ (column mol m-2 vs surface ug m-3).

Use case 5: Aviation weather (METAR)

Goal. Station observations for flight or disruption context.

Call. /api/v2/transport/aviation/metar?ids=KJFK,EGLL (live-verified path).

Strength. Structured METAR plus raw text where provided.
Pitfalls. Consultative only - not a substitute for official preflight briefing. Blob ingest can 503 if not loaded.

Use case 6: Tides and marine

Goal. Tide predictions and wave conditions for coastal ops.

Calls. /api/v2/transport/tides, /api/v2/transport/marine.

Strength. Station resolution + prediction series.
Pitfalls. Datum and units - read response carefully.

Use case 7: Weather-aware operations compose (Earth-only)

Goal. Join weather + hazards + (optional) METAR along a route - still within Earth.

Pattern. Multiple v2 calls, client-side join by time and location.

Portal recipe: weather-aware-operations.md.

Strength. One direction for physical risk context.
Pitfalls. Time alignment is your job.

Use case 8: Climate and long history

Goal. Climate history / projections surfaces for research.

Calls. Climate and history endpoints under Environment (see portal Earth page).

Strength. Named climate institutions.
Pitfalls. Not short-term ops weather.

Antipatterns

Using wrong METAR path (/api/v1/aviation/...)
Omitting hazard disclaimers in UI
Treating forecast guidance as official warnings
Mixing AQ units without conversion notes
Hiding provenance and attribution blocks

Scenarios where Earth alone is enough

Ops weather and AQ boards
Hazard monitoring agents
Grid demand dashboards
Aviation station weather tools
Coastal tide tools

Live verification (2026-07-24)

Call	Result
`/api/v2/weather` Berlin	200, multi-model provenance
`/api/v2/hazards/earthquakes`	200, 19 matched
`/api/v2/energy/grid` US48 demand	200
`/api/v2/air-quality`	200
`/api/v2/transport/aviation/metar?ids=KJFK`	200

Where to go next

Portal: Sugra Earth direction + sources
Recipes: weather-aware-operations, grid-load-monitor
Cookbook: 08_aviation_airport_search.py
Series: News (previous), Research (next)

#	Direction	Status
1-5	Finance … News	Published
6	Earth	This article
7	Research	Next