---
title: "Ops brief from Sugra Earth"
description: "Join weather, hazards, grid, and aviation into one physical-world operations brief."
slug: compose-earth-ops
status: published
published_at: 2026-07-14
author: Arman Obosyan
author_url: https://sugra.systems/about
section: composition
series_order: 10
primary_keyword: sugra earth operations composition
hero_image: /blog/images/posts/compose-earth-ops-hero.jpg
hero_alt: "Ops brief from Sugra Earth - Sugra API blog"
og_image: /blog/images/posts/compose-earth-ops-hero.jpg
tags:
  - composition
  - earth
  - ops
---

# Composition: Earth physical ops stack

**Series:** compositions (3 of 4)  
**Prerequisites:** [Platform intro](/blog/platform-intro), [Earth](/blog/sugra-earth)  
**Directions:** Earth only (multi-module composition inside one direction)  
**Auth:** `x-api-key`  

Not every composition crosses directions. This one stays inside **Earth** and joins weather, hazards, grid, and aviation into one operations brief.

Portal recipes: `weather-aware-operations`, `grid-load-monitor`.

---

## Goal

For a site or region (lat/lon + optional ICAO + grid region):

1. Current multi-model weather at the point  
2. Nearby / global hazards of interest  
3. Grid demand (or other metric) for the power region  
4. Optional METAR for the nearest/ops airport  

Output a single ops JSON for dashboards or agents. Forecast guidance only - not an official warning service.

---

## Call sequence

```text
[Earth] GET /api/v2/weather?lat=&lon=
[Earth] GET /api/v2/hazards/earthquakes?window=day&min_magnitude=4.5&limit=20
        (or other /hazards/* types as needed)
[Earth] GET /api/v2/energy/grid?region=US48&metric=demand&limit=24
[Earth] GET /api/v2/air-quality?lat=&lon=          (optional)
[Earth] GET /api/v2/transport/aviation/metar?ids=KJFK   (optional)
         -> ops_brief
```

```bash
H="x-api-key: $SUGRA_API_KEY"
B=https://sugra.ai
LAT=40.64
LON=-73.78

curl -H "$H" "$B/api/v2/weather?lat=$LAT&lon=$LON"
curl -H "$H" "$B/api/v2/hazards/earthquakes?window=day&min_magnitude=4.5&limit=10"
curl -H "$H" "$B/api/v2/energy/grid?region=US48&metric=demand&limit=24"
curl -H "$H" "$B/api/v2/transport/aviation/metar?ids=KJFK"
```

**Path note:** METAR is under `/api/v2/transport/aviation/metar?ids=`, not `/api/v1/aviation/metar`.

---

## Client package (example)

```python
ops_brief = {
    "location": {"lat": lat, "lon": lon},
    "weather": {
        "temperature_c": weather["weather"]["temperature_c"],
        "wind_speed_ms": weather["weather"]["wind_speed_ms"],
        "model": weather.get("forecast", {}).get("name"),
        "provenance": weather.get("provenance"),
        "attribution": weather.get("attribution"),
    },
    "hazards": {
        "earthquakes_matched": hazards.get("total_matched"),
        "events": hazards.get("events", [])[:5],
        "disclaimer": hazards.get("disclaimer"),
    },
    "grid": {
        "region": grid.get("region"),
        "metric": grid.get("metric"),
        "latest": (grid.get("series") or [None])[0],
        "source_meta": grid_meta.get("source"),
    },
    "aviation": metar_payload,  # may be null if 503 / not ingested
}
```

Keep `meta.source` / attribution blocks for each leg.

---

## Why this composition works

| Module | Contribution |
|---|---|
| Weather v2 | Multi-model point conditions + per-field provenance |
| Hazards v2 | Unified event schema |
| Energy grid | Infrastructure load context |
| Aviation METAR | Station truth near hubs |

All under one direction, one key, mostly standard `data`/`meta` envelope.

---

## Cadence and quota

| Leg | Suggested refresh |
|---|---|
| Weather | 15-60 minutes |
| Hazards | 15-60 minutes |
| Grid | 15-60 minutes (region-dependent publish) |
| METAR | 15-30 minutes when aviation matters |

Full brief: about **3-5 calls** per refresh.

---

## Optional cross-direction extensions (out of scope here)

- Add [NetAtlas](/blog/sugra-netatlas) outage alerts for connectivity context  
- Add [News](/blog/sugra-news) disaster category headlines  

Those become multi-direction compositions; keep them explicit so failure domains stay clear.

---

## Failure modes

| Failure | Handling |
|---|---|
| Weather 503 | Last-good weather; flag stale |
| Hazards empty | Valid "no events above threshold" |
| METAR 503 / not ingested | Omit aviation block |
| Wrong region code on grid | 4xx - fix enum from docs |

---

## Read next

- [Earth](/blog/sugra-earth)  
- Next composition: [Event stack](/blog/compose-event-stack)  
- [Series TOC](/blog/platform-intro) · [Conclusion](/blog/series-conclusion)