---
title: "Sugra Earth"
description: "Weather, climate, disasters, energy, and satellite - the physical world as an API with provenance."
slug: sugra-earth
status: published
published_at: 2026-06-23
author: Arman Obosyan
author_url: https://sugra.systems/about
section: foundation
series_order: 6
primary_keyword: sugra earth weather api
hero_image: /blog/images/posts/sugra-earth-hero.jpg
hero_alt: "Sugra Earth - Sugra API blog"
og_image: /blog/images/posts/sugra-earth-hero.jpg
tags:
  - earth
  - weather
  - api
---

# 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):

```json
{
  "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

```bash
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

1. Using wrong METAR path (`/api/v1/aviation/...`)  
2. Omitting hazard disclaimers in UI  
3. Treating forecast guidance as official warnings  
4. Mixing AQ units without conversion notes  
5. 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 |

---