koala73/worldmonitor/assess-energy-shock

assess-energy-shock

Use this skill when the user asks "what happens if Hormuz closes?", "how exposed is Japan to a LNG disruption?", or "what fuel products are most affected by a chokepoint shock?". It computes an on-demand oil and gas shock scenario from seeded JODI, Comtrade, IEA, PortWatch, and gas-storage inputs.

Authentication

Server-to-server callers (agents, scripts, SDKs) MUST present an API key in the X-WorldMonitor-Key header. Authorization: Bearer ... is for MCP/OAuth or Clerk JWTs - not raw API keys.

X-WorldMonitor-Key: wm_0123456789abcdef0123456789abcdef01234567

Issue a key at https://www.worldmonitor.app/pro.

Endpoint

GET https://www.worldmonitor.app/api/intelligence/v1/compute-energy-shock

Parameters

Response shape

{
  "countryCode": "JP",
  "chokepointId": "hormuz_strait",
  "disruptionPct": 50,
  "gulfCrudeShare": 0.42,
  "crudeLossKbd": 210.5,
  "preCrisisBaseline": { "basis": "comtrade_monthly", "fromMonth": "2025-02", "toMonth": "2026-01", "monthsCovered": 12, "gulfCrudeShare": 0.42, "crudeLossKbd": 380.2, "crudeLossAfterBypassKbd": 210.5 },
  "currentFlows": { "basis": "comtrade_monthly", "fromMonth": "2026-06", "toMonth": "2026-08", "monthsCovered": 3, "gulfCrudeShare": 0.27, "crudeLossKbd": 135.3 },
  "products": [
    { "product": "diesel", "outputLossKbd": 58.4, "demandKbd": 820.1, "deficitPct": 7.1 }
  ],
  "effectiveCoverDays": 92,
  "assessment": "...",
  "dataAvailable": true,
  "coverageLevel": "partial",
  "limitations": ["..."],
  "degraded": false,
  "chokepointConfidence": "none",
  "liveFlowRatio": 0.88,
  "gasSensitivity": {
    "lngShareOfImports": 1,
    "dataMonth": "2026-07",
    "modelBasis": "comtrade_lng_origin_share",
    "preCrisisBaseline": { "basis": "comtrade_monthly", "fromMonth": "2025-02", "toMonth": "2026-01", "monthsCovered": 12, "hormuzLngShare": 0.064, "lngDisruptionTj": 8774.3 },
    "currentFlows": { "basis": "comtrade_monthly", "fromMonth": "2026-06", "toMonth": "2026-08", "monthsCovered": 3, "hormuzLngShare": 0.0044, "lngDisruptionTj": 603.2 },
    "lngDisruptionTj": 8774.3,
    "deficitPct": 2.9,
    "assessment": "...",
    "dataAvailable": true
  }
}

dataAvailable: false or coverageLevel: "unsupported" means inputs are insufficient, not zero exposure.

Oil reports two Gulf crude shares. preCrisisBaseline drives gulfCrudeShare, crudeLossKbd, products and effectiveCoverDays. With basis comtrade_monthly it uses the importer's own UN Comtrade filings for the 12 months before the 2026 Hormuz crisis (Feb 2025 to Jan 2026), at least 9 of them. An importer that files no monthly crude partners to Comtrade uses its own national statistics instead, with basis national_monthly: Turkey from the monthly petroleum reports of EPDK, its energy market regulator. Each window takes its basis separately, so a national currentFlows can sit beside a comtrade_annual baseline when the national statistics cover fewer than 9 baseline months. With fewer than 9 monthly filings it falls back to comtrade_annual, the annual partner share for the newest year the importer has filed (2025 for China). Read basis, fromMonth, toMonth and monthsCovered for the period a figure covers. currentFlows covers the latest 3 monthly filings since March 2026 and is reported beside the baseline; it is absent when fewer than 3 monthly filings since March 2026 are available or the latest fetch failed, and limitations says which. For Hormuz, when per-exporter shares exist (preCrisisBaseline.crudeLossAfterBypassKbd is present), crudeLossKbd is the steady-state loss after bypass rerouting (Saudi East-West pipeline to Yanbu, UAE ADCOP to Fujairah, Iraqi Kirkuk-Ceyhan); preCrisisBaseline.crudeLossKbd is the loss before it, and the first month of a closure runs at that rate. The bypass figures are dated estimates listed in limitations. currentFlows.crudeLossKbd gets no bypass recovery and counts all Gulf-origin crude, including cargoes already loading at Yanbu or Fujairah (Comtrade records origin, not route), so treat it as an upper bound. State which baseline a figure uses. Both shares are value-weighted (import value, not barrels), except national_monthly, which is by volume (tonnes), and include the chokepoint route factor (1.0 for Hormuz and Bab el-Mandeb, 0.6 for Suez, 0.7 for Malacca), so on Suez and Malacca they are below the importer's measured Gulf share. A crudeLossKbd of 0 with a limitation saying the oil loss is not modeled means no estimate, not zero exposure. An effectiveCoverDays of -1 marks a net oil exporter (from the IEA flag, or, for a country without an IEA record, from JODI when crude production is positive, crude exports exceed imports and production covers refinery intake when intake is reported, with unreported imports counting as zero; reported imports must be finite and nonnegative, and an invalid reported figure disqualifies the row; a limitation gives the figures): no import-cover duration applies. A disruption mainly hits export revenue but can still reach refiners that import Gulf crude or products, so read crudeLossKbd and products before calling domestic supply unaffected. In both mode gas inputs alone can make dataAvailable true, so check the oil limitations before reporting oil losses or cover. Missing or invalid LNG imports or nonpositive demand suppress gasSensitivity. Observed zero LNG imports remain valid.

For IEA members, effectiveCoverDays turns IEA days of cover into barrels at JODI's net oil imports (crude and products, imports less exports, day-weighted) for the calendar year before IEA's data month, a proxy for the net imports IEA counts days against (IEA also deducts naphtha, adjusts for stock changes and converts products to crude-oil equivalent); when no eligible prior-year netOilImports value is available (JODI needs at least 9 complete months, and a net-exporting year has none), it falls back to crude imports, and a limitation starting IEA days of cover converted to barrels names the basis used. Importers outside the IEA have no IEA stock data. When they report month-end crude and product stocks to JODI (India, Taiwan, Thailand, the Philippines among them), effectiveCoverDays comes from reportedStocks: month the stocks closed, crudeMb, productsMb, totalMb, and stockDays (the total in days of crude imports). JODI stocks are what the country reports as held on its territory; whether government reserves are included depends on the reporter. Stocks more than 12 months older than the JODI flow month are not used. A country that reports no stocks (China) has no cover: effectiveCoverDays is 0 and a limitation starts Oil stock cover not modeled. Cover values are capped: a capped result is exactly effectiveCoverDays: 730, meaning 730 days or more, not an estimate of 730. Cover applies only when the oil loss is modeled; otherwise reportedStocks still reports the stock, effectiveCoverDays is 0 and stockDays is absent. A net exporter keeps effectiveCoverDays: -1 with reportedStocks and no stockDays. totalMb is rounded from the unrounded sum, so it can differ from crudeMb + productsMb by 0.1. Report it as JODI-reported stock, never as IEA cover. An IEA member whose IEA record is anomalous or incomplete gets no cover from either source, and the limitation says so. reserveEstimate is deprecated and no longer returned. Missing or invalid LNG imports or nonpositive demand suppress gasSensitivity. Observed zero LNG imports remain valid.

products[].demandKbd is JODI demand. For a product JODI gives no demand for in the pre-crisis window or the latest month, it is the country's own annual final consumption when that year is the JODI flow month's or at most 3 years before it (Malaysia from DOSM), and a limitation starting Product demand for names the source, year and products. Final consumption excludes fuel burned for power generation, so demand is understated where power plants burn these fuels. A country with no demand from either has an empty products array. products is also empty when the oil loss is not modeled, and a net exporter or a country without enough data gets that assessment instead, so read assessment and limitations before calling the demand missing.

Gas modelBasis says where the route share comes from. For hormuz_strait it is comtrade_lng_origin_share: the importer's measured share of LNG imports from Qatar and the UAE (UN Comtrade HS 271111; Oman's Qalhat terminal loads outside the Strait). gasSensitivity.preCrisisBaseline covers the 12 months before the crisis (2025-02 to 2026-01) when the importer filed them monthly, otherwise the 2025 calendar year (basis: comtrade_annual, 2024 for late filers); the headline lngDisruptionTj equals its lngDisruptionTj, or that of gasSensitivity.currentFlows when the pre-crisis share is unavailable (the assessment says which), and the headline deficitPct is that loss over recorded demand. The baselines carry no deficitPct. gasSensitivity.currentFlows covers the latest three monthly observations since 2026-03. A share is withheld when more than 10% of the importer's LNG imports are not attributed to a named partner. A baseline is absent when unavailable; never read an absent baseline as zero. An importer with recorded LNG imports and no measured share has no gasSensitivity, and a limitation starts LNG origin share unavailable. observed_zero_lng_imports marks zero recorded LNG imports. Other chokepoints use assumed_route_sensitivity: recorded monthly LNG imports multiplied by a fixed assumed route share. Current shipping flow does not scale it under either basis. Neither is a supply-shortage forecast. deficitPct is the assumed loss as a percentage of recorded demand and may exceed 100 when imports exceed demand. lngShareOfImports is a fraction and is absent when unknown.

Gas coverage is at most partial. Gas and combined mode chokepointConfidence is none because shipping data cannot establish confidence in country LNG exposure. degraded and portwatchCoverage describe shipping input availability, not gas freshness. Read gasSensitivity.dataMonth for the JODI observation month and storage.date separately. Empty dates mean unknown. A recent response does not make observations current.

gasImpact is deprecated and omitted. Use gasSensitivity for gas scenarios. Its storage contains national GIE observations only and has no bufferDays field. National stock divided by a marginal loss does not establish accessible stock, withdrawal capacity, or operational endurance. Never convert that ratio into country or company survival time.

Worked example

Japan, 50% Hormuz disruption, oil and gas:

curl -s --get -H "X-WorldMonitor-Key: $WM_API_KEY" \
  -H "User-Agent: worldmonitor-agent-skill/1.0" \
  'https://www.worldmonitor.app/api/intelligence/v1/compute-energy-shock' \
  --data-urlencode 'country_code=JP' \
  --data-urlencode 'chokepoint_id=hormuz_strait' \
  --data-urlencode 'disruption_pct=50' \
  --data-urlencode 'fuel_mode=both' \
  | jq '{assessment, coverageLevel, degraded, products, gasSensitivity}'

Content safety