eliott/worldmonitor
1
0
Fork 0
mirror of https://github.com/koala73/worldmonitor.git synced 2026-04-25 17:14:57 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
worldmonitor/docs/api/EconomicService.openapi.yaml
Sebastien Melki fcbb8bc0a1 feat(proto): unified OpenAPI bundle via sebuf v0.11.0 (#3341) 
* feat(proto): generate unified worldmonitor.openapi.yaml bundle

Adds a third protoc-gen-openapiv3 invocation that merges every service
into a single docs/api/worldmonitor.openapi.yaml spanning all 68 RPCs,
using the new bundle support shipped in sebuf 0.11.0
(SebastienMelki/sebuf#158).

Per-service YAML/JSON files are untouched and continue to back the
Mintlify docs in docs/docs.json. The bundle runs with strategy: all and
bundle_only=true so only the aggregate file is emitted, avoiding
duplicate-output conflicts with the existing per-service generator.

Requires protoc-gen-openapiv3 >= v0.11.0 locally:
  go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-openapiv3@v0.11.0

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(proto): bump sebuf to v0.11.0 and document unified OpenAPI bundle

- Makefile: SEBUF_VERSION v0.7.0 → v0.11.0 (required for bundle support).
- proto/buf.gen.yaml: point bundle_server at https://api.worldmonitor.app.
- CONTRIBUTING.md: new "OpenAPI Output" section covering per-service specs
  vs the unified worldmonitor.openapi.yaml bundle, plus a note that all
  three sebuf plugins must be installed from the pinned version.
- AGENTS.md: clarify that `make generate` also produces the unified spec
  and requires sebuf v0.11.0.
- CHANGELOG.md: Unreleased entry announcing the bundle and version bump.

Also regenerates the bundle with the updated server URL.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(codegen): regenerate TS client/server with sebuf v0.11.0

Mechanical output of the bumped protoc-gen-ts-client and
protoc-gen-ts-server. Two behavioral improvements roll in from sebuf:

- Proto enum fields now use the proper `*_UNSPECIFIED` sentinel in
  default-value checks instead of the empty string, so generated
  query-string serializers correctly omit enum params only when they
  actually equal the proto default.
- `repeated string` query params now serialize via
  `forEach(v => params.append(...))` instead of being coerced through
  `String(req.field)`, matching the existing `parseStringArray()`
  contract on the server side.

All files also drop the `// @ts-nocheck` header that earlier sebuf
versions emitted — 0.11.0 output type-checks cleanly under our tsconfig.

No hand edits. Reproduce with `make install-plugins && make generate`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(proto): bump sebuf v0.11.0 → v0.11.1, realign tests with repeated-param wire format

- Bump SEBUF_VERSION to v0.11.1, pulling in the OpenAPI fix for repeated
  scalar query params (SebastienMelki/sebuf#161). `repeated string` fields
  now emit `type: array` + `items.type: string` + `style: form` +
  `explode: true` instead of `type: string`, so SDK generators consuming
  the unified bundle produce correct array clients.
- Regenerate all 12 OpenAPI specs (unified bundle + Aviation, Economic,
  Infrastructure, Market, Trade per-service). TS client/server codegen
  is byte-identical to v0.11.0 — only the OpenAPI emitter was out of sync.
- Update three tests that asserted the pre-v0.11 comma-joined wire format
  (`symbols=AAPL,MSFT`) to match the current repeated-param form
  (`symbols=AAPL&symbols=MSFT`) produced by `params.append(...)`:
  - tests/market-service-symbol-casing.test.mjs (2 cases: getAll)
  - tests/stock-analysis-history.test.mts
  - tests/stock-backtest.test.mts

Locally: test:data 6619/6619 pass, typecheck clean, lint exit 0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Apply suggestions from code review

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
2026-04-23 16:24:03 +03:00

2392 lines
94 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
openapi: 3.1.0
info:
title: EconomicService API
version: 1.0.0
paths:
/api/economic/v1/get-fred-series:
get:
tags:
- EconomicService
summary: GetFredSeries
description: GetFredSeries retrieves time series data from the Federal Reserve Economic Data.
operationId: GetFredSeries
parameters:
- name: series_id
in: query
description: FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL").
required: false
schema:
type: string
- name: limit
in: query
description: Maximum number of observations to return. Defaults to 120.
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetFredSeriesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/list-world-bank-indicators:
get:
tags:
- EconomicService
summary: ListWorldBankIndicators
description: ListWorldBankIndicators retrieves development indicator data from the World Bank.
operationId: ListWorldBankIndicators
parameters:
- name: indicator_code
in: query
description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD").
required: false
schema:
type: string
- name: country_code
in: query
description: Optional country filter (ISO 3166-1 alpha-2).
required: false
schema:
type: string
- name: year
in: query
description: Optional year filter. Defaults to latest available.
required: false
schema:
type: integer
format: int32
- name: page_size
in: query
description: Maximum items per page.
required: false
schema:
type: integer
format: int32
- name: cursor
in: query
description: Cursor for next page.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListWorldBankIndicatorsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-energy-prices:
get:
tags:
- EconomicService
summary: GetEnergyPrices
description: GetEnergyPrices retrieves current energy commodity prices from EIA.
operationId: GetEnergyPrices
parameters:
- name: commodities
in: query
description: Optional commodity filter. Empty returns all tracked commodities.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnergyPricesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-macro-signals:
get:
tags:
- EconomicService
summary: GetMacroSignals
description: GetMacroSignals computes 7 macro signals from 6 upstream sources with BUY/CASH verdict.
operationId: GetMacroSignals
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetMacroSignalsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-energy-capacity:
get:
tags:
- EconomicService
summary: GetEnergyCapacity
description: GetEnergyCapacity retrieves installed capacity data (solar, wind, coal) from EIA.
operationId: GetEnergyCapacity
parameters:
- name: energy_sources
in: query
description: |-
Energy source codes to query (e.g., "SUN", "WND", "COL").
Empty returns all tracked sources (SUN, WND, COL).
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: years
in: query
description: Number of years of historical data. Default 20 if not set.
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnergyCapacityResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-bis-policy-rates:
get:
tags:
- EconomicService
summary: GetBisPolicyRates
description: GetBisPolicyRates retrieves central bank policy rates from BIS.
operationId: GetBisPolicyRates
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetBisPolicyRatesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-bis-exchange-rates:
get:
tags:
- EconomicService
summary: GetBisExchangeRates
description: GetBisExchangeRates retrieves effective exchange rates from BIS.
operationId: GetBisExchangeRates
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetBisExchangeRatesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-bis-credit:
get:
tags:
- EconomicService
summary: GetBisCredit
description: GetBisCredit retrieves credit-to-GDP ratio data from BIS.
operationId: GetBisCredit
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetBisCreditResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-fred-series-batch:
post:
tags:
- EconomicService
summary: GetFredSeriesBatch
description: GetFredSeriesBatch retrieves multiple FRED series in a single call.
operationId: GetFredSeriesBatch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetFredSeriesBatchRequest'
required: true
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetFredSeriesBatchResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/list-grocery-basket-prices:
get:
tags:
- EconomicService
summary: ListGroceryBasketPrices
description: ListGroceryBasketPrices retrieves grocery basket price comparison across 24 countries worldwide.
operationId: ListGroceryBasketPrices
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListGroceryBasketPricesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/list-bigmac-prices:
get:
tags:
- EconomicService
summary: ListBigMacPrices
description: ListBigMacPrices retrieves Big Mac Index prices across Middle East countries.
operationId: ListBigMacPrices
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListBigMacPricesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-national-debt:
get:
tags:
- EconomicService
summary: GetNationalDebt
description: GetNationalDebt retrieves national debt clock data for all countries.
operationId: GetNationalDebt
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetNationalDebtResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/list-fuel-prices:
get:
tags:
- EconomicService
summary: ListFuelPrices
description: ListFuelPrices retrieves retail gasoline and diesel prices across 30+ countries.
operationId: ListFuelPrices
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListFuelPricesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-bls-series:
get:
tags:
- EconomicService
summary: GetBlsSeries
description: GetBlsSeries retrieves BLS-only series not available on FRED (CES, LAUMT, CIU).
operationId: GetBlsSeries
parameters:
- name: series_id
in: query
description: BLS series ID (e.g. "CES0500000001", "CIU1010000000000A").
required: false
schema:
type: string
- name: limit
in: query
description: Maximum number of observations to return. Defaults to 60.
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetBlsSeriesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-economic-calendar:
get:
tags:
- EconomicService
summary: GetEconomicCalendar
description: GetEconomicCalendar retrieves upcoming major economic events (FOMC, CPI, NFP, etc).
operationId: GetEconomicCalendar
parameters:
- name: fromDate
in: query
required: false
schema:
type: string
- name: toDate
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEconomicCalendarResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-crude-inventories:
get:
tags:
- EconomicService
summary: GetCrudeInventories
description: GetCrudeInventories retrieves the 8 most recent weeks of US crude oil stockpile data from EIA (WCRSTUS1).
operationId: GetCrudeInventories
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCrudeInventoriesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-nat-gas-storage:
get:
tags:
- EconomicService
summary: GetNatGasStorage
description: GetNatGasStorage retrieves the 8 most recent weeks of US natural gas working gas storage from EIA (NW2_EPG0_SWO_R48_BCF).
operationId: GetNatGasStorage
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetNatGasStorageResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-ecb-fx-rates:
get:
tags:
- EconomicService
summary: GetEcbFxRates
description: GetEcbFxRates retrieves daily ECB official reference rates for EUR/major currency pairs.
operationId: GetEcbFxRates
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEcbFxRatesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-eurostat-country-data:
get:
tags:
- EconomicService
summary: GetEurostatCountryData
description: GetEurostatCountryData retrieves per-country CPI, unemployment, and GDP growth for 10 EU member states.
operationId: GetEurostatCountryData
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEurostatCountryDataResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-eu-gas-storage:
get:
tags:
- EconomicService
summary: GetEuGasStorage
description: GetEuGasStorage retrieves EU aggregate natural gas storage fill % from GIE AGSI+.
operationId: GetEuGasStorage
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEuGasStorageResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-eu-yield-curve:
get:
tags:
- EconomicService
summary: GetEuYieldCurve
description: GetEuYieldCurve retrieves the ECB Euro Area AAA sovereign yield curve (Svensson model spot rates).
operationId: GetEuYieldCurve
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEuYieldCurveResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-eu-fsi:
get:
tags:
- EconomicService
summary: GetEuFsi
description: GetEuFsi retrieves the ECB CISS (Composite Indicator of Systemic Stress) for the Euro area.
operationId: GetEuFsi
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEuFsiResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-economic-stress:
get:
tags:
- EconomicService
summary: GetEconomicStress
description: GetEconomicStress retrieves the composite Economic Stress Index (0-100) from 6 FRED series.
operationId: GetEconomicStress
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEconomicStressResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-fao-food-price-index:
get:
tags:
- EconomicService
summary: GetFaoFoodPriceIndex
description: GetFaoFoodPriceIndex retrieves the FAO Food Price Index for the past 12 months.
operationId: GetFaoFoodPriceIndex
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetFaoFoodPriceIndexResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-oil-stocks-analysis:
get:
tags:
- EconomicService
summary: GetOilStocksAnalysis
description: GetOilStocksAnalysis retrieves the IEA oil stocks days-of-cover ranking and regional summary.
operationId: GetOilStocksAnalysis
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetOilStocksAnalysisResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-oil-inventories:
get:
tags:
- EconomicService
summary: GetOilInventories
operationId: GetOilInventories
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetOilInventoriesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/economic/v1/get-energy-crisis-policies:
get:
tags:
- EconomicService
summary: GetEnergyCrisisPolicies
description: GetEnergyCrisisPolicies retrieves government policy responses to the 2026 energy crisis from the IEA tracker.
operationId: GetEnergyCrisisPolicies
parameters:
- name: country_code
in: query
description: Optional ISO-2 country code filter.
required: false
schema:
type: string
- name: category
in: query
description: 'Optional category filter: "conservation" or "consumer_support".'
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnergyCrisisPoliciesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
message:
type: string
description: Error message (e.g., 'user not found', 'database connection failed')
description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
FieldViolation:
type: object
properties:
field:
type: string
description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
description:
type: string
description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
required:
- field
- description
description: FieldViolation describes a single validation error for a specific field.
ValidationError:
type: object
properties:
violations:
type: array
items:
$ref: '#/components/schemas/FieldViolation'
description: List of validation violations
required:
- violations
description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
GetFredSeriesRequest:
type: object
properties:
seriesId:
type: string
minLength: 1
description: FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL").
limit:
type: integer
format: int32
description: Maximum number of observations to return. Defaults to 120.
required:
- seriesId
description: GetFredSeriesRequest specifies which FRED series to retrieve.
GetFredSeriesResponse:
type: object
properties:
series:
$ref: '#/components/schemas/FredSeries'
description: GetFredSeriesResponse contains the requested FRED series data.
FredSeries:
type: object
properties:
seriesId:
type: string
minLength: 1
description: Series identifier (e.g., "GDP", "UNRATE", "CPIAUCSL").
title:
type: string
description: Series title.
units:
type: string
description: Unit of measurement.
frequency:
type: string
description: Data frequency (e.g., "Monthly", "Quarterly").
observations:
type: array
items:
$ref: '#/components/schemas/FredObservation'
required:
- seriesId
description: FredSeries represents a FRED time series with metadata.
FredObservation:
type: object
properties:
date:
type: string
description: Observation date as YYYY-MM-DD string.
value:
type: number
format: double
description: Observation value.
description: FredObservation represents a single data point from a FRED economic series.
ListWorldBankIndicatorsRequest:
type: object
properties:
indicatorCode:
type: string
minLength: 1
description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD").
countryCode:
type: string
description: Optional country filter (ISO 3166-1 alpha-2).
year:
type: integer
format: int32
description: Optional year filter. Defaults to latest available.
pageSize:
type: integer
format: int32
description: Maximum items per page.
cursor:
type: string
description: Cursor for next page.
required:
- indicatorCode
description: ListWorldBankIndicatorsRequest specifies filters for retrieving World Bank data.
ListWorldBankIndicatorsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WorldBankCountryData'
pagination:
$ref: '#/components/schemas/PaginationResponse'
description: ListWorldBankIndicatorsResponse contains World Bank indicator data.
WorldBankCountryData:
type: object
properties:
countryCode:
type: string
minLength: 1
description: ISO 3166-1 alpha-2 country code.
countryName:
type: string
description: Country name.
indicatorCode:
type: string
minLength: 1
description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD").
indicatorName:
type: string
description: Indicator name.
year:
type: integer
format: int32
description: Data year.
value:
type: number
format: double
description: Indicator value.
required:
- countryCode
- indicatorCode
description: WorldBankCountryData represents a World Bank indicator value for a country.
PaginationResponse:
type: object
properties:
nextCursor:
type: string
description: Cursor for fetching the next page. Empty string indicates no more pages.
totalCount:
type: integer
format: int32
description: Total count of items matching the query, if known. Zero if the total is unknown.
description: PaginationResponse contains pagination metadata returned alongside list results.
GetEnergyPricesRequest:
type: object
properties:
commodities:
type: array
items:
type: string
description: Optional commodity filter. Empty returns all tracked commodities.
description: GetEnergyPricesRequest specifies which energy commodities to retrieve.
GetEnergyPricesResponse:
type: object
properties:
prices:
type: array
items:
$ref: '#/components/schemas/EnergyPrice'
description: GetEnergyPricesResponse contains energy price data.
EnergyPrice:
type: object
properties:
commodity:
type: string
minLength: 1
description: Energy commodity identifier.
name:
type: string
description: Human-readable name (e.g., "WTI Crude Oil", "Henry Hub Natural Gas").
price:
type: number
format: double
description: Current price in USD.
unit:
type: string
description: Unit of measurement (e.g., "$/barrel", "$/MMBtu").
change:
type: number
format: double
description: Percentage change from previous period.
priceAt:
type: integer
format: int64
description: 'Price date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
required:
- commodity
description: EnergyPrice represents a current energy commodity price from EIA.
GetMacroSignalsRequest:
type: object
description: GetMacroSignalsRequest requests the current macro signal dashboard.
GetMacroSignalsResponse:
type: object
properties:
timestamp:
type: string
description: ISO 8601 timestamp of computation.
verdict:
type: string
description: 'Overall verdict: "BUY", "CASH", or "UNKNOWN".'
bullishCount:
type: integer
format: int32
description: Number of bullish signals.
totalCount:
type: integer
format: int32
description: Total number of evaluated signals (excluding UNKNOWN).
signals:
$ref: '#/components/schemas/MacroSignals'
meta:
$ref: '#/components/schemas/MacroMeta'
unavailable:
type: boolean
description: True when upstream data is unavailable (fallback result).
description: GetMacroSignalsResponse contains the full macro signal dashboard with 7 signals and verdict.
MacroSignals:
type: object
properties:
liquidity:
$ref: '#/components/schemas/LiquiditySignal'
flowStructure:
$ref: '#/components/schemas/FlowStructureSignal'
macroRegime:
$ref: '#/components/schemas/MacroRegimeSignal'
technicalTrend:
$ref: '#/components/schemas/TechnicalTrendSignal'
hashRate:
$ref: '#/components/schemas/HashRateSignal'
priceMomentum:
$ref: '#/components/schemas/PriceMomentumSignal'
fearGreed:
$ref: '#/components/schemas/FearGreedSignal'
description: MacroSignals contains all 7 individual signal computations.
LiquiditySignal:
type: object
properties:
status:
type: string
description: '"SQUEEZE", "NORMAL", or "UNKNOWN".'
value:
type: number
format: double
description: JPY 30d ROC percentage, absent if unavailable.
sparkline:
type: array
items:
type: number
format: double
description: Last 30 JPY close prices.
description: LiquiditySignal tracks JPY 30d rate of change as a liquidity proxy.
FlowStructureSignal:
type: object
properties:
status:
type: string
description: '"PASSIVE GAP", "ALIGNED", or "UNKNOWN".'
btcReturn5:
type: number
format: double
description: BTC 5-day return percentage.
qqqReturn5:
type: number
format: double
description: QQQ 5-day return percentage.
description: FlowStructureSignal compares BTC vs QQQ 5-day returns.
MacroRegimeSignal:
type: object
properties:
status:
type: string
description: '"RISK-ON", "DEFENSIVE", or "UNKNOWN".'
qqqRoc20:
type: number
format: double
description: QQQ 20d ROC percentage.
xlpRoc20:
type: number
format: double
description: XLP 20d ROC percentage.
description: MacroRegimeSignal compares QQQ vs XLP 20-day rate of change.
TechnicalTrendSignal:
type: object
properties:
status:
type: string
description: '"BULLISH", "BEARISH", "NEUTRAL", or "UNKNOWN".'
btcPrice:
type: number
format: double
description: Current BTC price.
sma50:
type: number
format: double
description: 50-day simple moving average.
sma200:
type: number
format: double
description: 200-day simple moving average.
vwap30d:
type: number
format: double
description: 30-day volume-weighted average price.
mayerMultiple:
type: number
format: double
description: Mayer multiple (BTC price / SMA200).
sparkline:
type: array
items:
type: number
format: double
description: Last 30 BTC close prices.
description: TechnicalTrendSignal evaluates BTC price vs moving averages and VWAP.
HashRateSignal:
type: object
properties:
status:
type: string
description: '"GROWING", "DECLINING", "STABLE", or "UNKNOWN".'
change30d:
type: number
format: double
description: Hash rate change over 30 days as percentage.
description: HashRateSignal tracks Bitcoin hash rate momentum.
PriceMomentumSignal:
type: object
properties:
status:
type: string
description: '"STRONG", "MODERATE", "WEAK", or "UNKNOWN".'
description: PriceMomentumSignal uses the Mayer Multiple (price/SMA200) as a market-adaptive signal.
FearGreedSignal:
type: object
properties:
status:
type: string
description: Classification label (e.g., "Extreme Fear", "Greed").
value:
type: integer
format: int32
description: Current index value (0-100).
history:
type: array
items:
$ref: '#/components/schemas/FearGreedHistoryEntry'
description: FearGreedSignal tracks the Crypto Fear & Greed index.
FearGreedHistoryEntry:
type: object
properties:
value:
type: integer
maximum: 100
minimum: 0
format: int32
description: Index value (0-100).
date:
type: string
description: Date string (YYYY-MM-DD).
description: FearGreedHistoryEntry is a single day's Fear & Greed index reading.
MacroMeta:
type: object
properties:
qqqSparkline:
type: array
items:
type: number
format: double
description: Last 30 QQQ close prices for sparkline.
description: MacroMeta contains supplementary chart data.
GetEnergyCapacityRequest:
type: object
properties:
energySources:
type: array
items:
type: string
description: |-
Energy source codes to query (e.g., "SUN", "WND", "COL").
Empty returns all tracked sources (SUN, WND, COL).
years:
type: integer
format: int32
description: Number of years of historical data. Default 20 if not set.
GetEnergyCapacityResponse:
type: object
properties:
series:
type: array
items:
$ref: '#/components/schemas/EnergyCapacitySeries'
EnergyCapacitySeries:
type: object
properties:
energySource:
type: string
name:
type: string
data:
type: array
items:
$ref: '#/components/schemas/EnergyCapacityYear'
EnergyCapacityYear:
type: object
properties:
year:
type: integer
format: int32
capacityMw:
type: number
format: double
GetBisPolicyRatesRequest:
type: object
description: GetBisPolicyRatesRequest requests central bank policy rates.
GetBisPolicyRatesResponse:
type: object
properties:
rates:
type: array
items:
$ref: '#/components/schemas/BisPolicyRate'
description: GetBisPolicyRatesResponse contains BIS policy rate data.
BisPolicyRate:
type: object
properties:
countryCode:
type: string
description: ISO 2-letter country code (US, GB, JP, etc.)
countryName:
type: string
description: Country or region name.
rate:
type: number
format: double
description: Current policy rate percentage.
previousRate:
type: number
format: double
description: Previous period rate percentage.
date:
type: string
description: Date as YYYY-MM.
centralBank:
type: string
description: Central bank name (e.g. "Federal Reserve").
description: BisPolicyRate represents a central bank policy rate from BIS.
GetBisExchangeRatesRequest:
type: object
description: GetBisExchangeRatesRequest requests effective exchange rates.
GetBisExchangeRatesResponse:
type: object
properties:
rates:
type: array
items:
$ref: '#/components/schemas/BisExchangeRate'
description: GetBisExchangeRatesResponse contains BIS effective exchange rate data.
BisExchangeRate:
type: object
properties:
countryCode:
type: string
description: ISO 2-letter country code.
countryName:
type: string
description: Country or region name.
realEer:
type: number
format: double
description: Real effective exchange rate index.
nominalEer:
type: number
format: double
description: Nominal effective exchange rate index.
realChange:
type: number
format: double
description: Percentage change from previous period (real).
date:
type: string
description: Date as YYYY-MM.
description: BisExchangeRate represents effective exchange rate indices from BIS.
GetBisCreditRequest:
type: object
description: GetBisCreditRequest requests credit-to-GDP ratio data.
GetBisCreditResponse:
type: object
properties:
entries:
type: array
items:
$ref: '#/components/schemas/BisCreditToGdp'
description: GetBisCreditResponse contains BIS credit-to-GDP data.
BisCreditToGdp:
type: object
properties:
countryCode:
type: string
description: ISO 2-letter country code.
countryName:
type: string
description: Country or region name.
creditGdpRatio:
type: number
format: double
description: Total credit as percentage of GDP.
previousRatio:
type: number
format: double
description: Previous quarter ratio.
date:
type: string
description: Date as YYYY-QN.
description: BisCreditToGdp represents total credit as percentage of GDP from BIS.
GetFredSeriesBatchRequest:
type: object
properties:
seriesIds:
type: array
items:
type: string
maxItems: 10
minItems: 1
description: FRED series IDs (e.g., "WALCL", "FEDFUNDS"). Max 10.
maxItems: 10
minItems: 1
limit:
type: integer
format: int32
description: Maximum number of observations per series. Defaults to 120.
description: GetFredSeriesBatchRequest looks up multiple FRED series in a single call.
GetFredSeriesBatchResponse:
type: object
properties:
results:
type: object
additionalProperties:
$ref: '#/components/schemas/FredSeries'
description: Map of series_id -> FRED series for found series.
fetched:
type: integer
format: int32
description: Number of series successfully fetched.
requested:
type: integer
format: int32
description: Number of series requested.
description: GetFredSeriesBatchResponse contains the requested FRED series data.
ResultsEntry:
type: object
properties:
key:
type: string
value:
$ref: '#/components/schemas/FredSeries'
ListGroceryBasketPricesRequest:
type: object
ListGroceryBasketPricesResponse:
type: object
properties:
countries:
type: array
items:
$ref: '#/components/schemas/CountryBasket'
fetchedAt:
type: string
cheapestCountry:
type: string
mostExpensiveCountry:
type: string
upstreamUnavailable:
type: boolean
wowAvgPct:
type: number
format: double
wowAvailable:
type: boolean
prevFetchedAt:
type: string
CountryBasket:
type: object
properties:
code:
type: string
name:
type: string
currency:
type: string
flag:
type: string
totalUsd:
type: number
format: double
fxRate:
type: number
format: double
items:
type: array
items:
$ref: '#/components/schemas/GroceryItemPrice'
wowPct:
type: number
format: double
GroceryItemPrice:
type: object
properties:
itemId:
type: string
itemName:
type: string
unit:
type: string
localPrice:
type: number
format: double
usdPrice:
type: number
format: double
currency:
type: string
sourceSite:
type: string
available:
type: boolean
ListBigMacPricesRequest:
type: object
ListBigMacPricesResponse:
type: object
properties:
countries:
type: array
items:
$ref: '#/components/schemas/BigMacCountryPrice'
fetchedAt:
type: string
cheapestCountry:
type: string
mostExpensiveCountry:
type: string
wowAvgPct:
type: number
format: double
wowAvailable:
type: boolean
prevFetchedAt:
type: string
BigMacCountryPrice:
type: object
properties:
code:
type: string
name:
type: string
currency:
type: string
flag:
type: string
localPrice:
type: number
format: double
usdPrice:
type: number
format: double
fxRate:
type: number
format: double
sourceSite:
type: string
available:
type: boolean
wowPct:
type: number
format: double
GetNationalDebtRequest:
type: object
description: GetNationalDebtRequest requests national debt data for all countries.
GetNationalDebtResponse:
type: object
properties:
entries:
type: array
items:
$ref: '#/components/schemas/NationalDebtEntry'
seededAt:
type: string
description: ISO 8601 timestamp when seed data was written.
unavailable:
type: boolean
description: True when upstream data is unavailable (fallback result).
description: GetNationalDebtResponse wraps the full list of national debt entries.
NationalDebtEntry:
type: object
properties:
iso3:
type: string
description: ISO3 country code (e.g. "USA").
debtUsd:
type: number
format: double
description: Total debt in USD at baseline_ts.
gdpUsd:
type: number
format: double
description: GDP in USD (nominal, latest year).
debtToGdp:
type: number
format: double
description: Debt as % of GDP.
annualGrowth:
type: number
format: double
description: Year-over-year debt growth percent (2023->2024).
perSecondRate:
type: number
format: double
description: Deficit-derived accrual in USD per second.
perDayRate:
type: number
format: double
description: Deficit-derived accrual in USD per day.
baselineTs:
type: string
format: int64
description: UTC ms timestamp anchoring the debt_usd figure (2024-01-01T00:00:00Z).
source:
type: string
description: Human-readable source string.
description: NationalDebtEntry holds debt data for a single country.
ListFuelPricesRequest:
type: object
ListFuelPricesResponse:
type: object
properties:
countries:
type: array
items:
$ref: '#/components/schemas/FuelCountryPrice'
fetchedAt:
type: string
cheapestGasoline:
type: string
cheapestDiesel:
type: string
mostExpensiveGasoline:
type: string
mostExpensiveDiesel:
type: string
wowAvailable:
type: boolean
prevFetchedAt:
type: string
sourceCount:
type: integer
format: int32
countryCount:
type: integer
format: int32
FuelCountryPrice:
type: object
properties:
code:
type: string
name:
type: string
currency:
type: string
flag:
type: string
gasoline:
$ref: '#/components/schemas/FuelPrice'
diesel:
$ref: '#/components/schemas/FuelPrice'
fxRate:
type: number
format: double
FuelPrice:
type: object
properties:
usdPrice:
type: number
format: double
localPrice:
type: number
format: double
grade:
type: string
source:
type: string
available:
type: boolean
wowPct:
type: number
format: double
observedAt:
type: string
GetBlsSeriesRequest:
type: object
properties:
seriesId:
type: string
description: BLS series ID (e.g. "CES0500000001", "CIU1010000000000A").
limit:
type: integer
format: int32
description: Maximum number of observations to return. Defaults to 60.
description: GetBlsSeriesRequest specifies which BLS series to retrieve.
GetBlsSeriesResponse:
type: object
properties:
series:
$ref: '#/components/schemas/BlsSeries'
description: GetBlsSeriesResponse contains the requested BLS series data.
BlsSeries:
type: object
properties:
seriesId:
type: string
description: BLS series ID (e.g. "CES0500000001").
title:
type: string
description: Human-readable series title.
units:
type: string
description: Unit of measure.
observations:
type: array
items:
$ref: '#/components/schemas/BlsObservation'
description: BlsSeries is a BLS time series with metadata and observations.
BlsObservation:
type: object
properties:
year:
type: string
description: Year of the observation.
period:
type: string
description: Period code (e.g. "M01" for January, "A01" for annual).
periodName:
type: string
description: Human-readable period name.
value:
type: string
description: Observed value.
description: BlsObservation is a single BLS data point.
GetEconomicCalendarRequest:
type: object
properties:
fromDate:
type: string
toDate:
type: string
GetEconomicCalendarResponse:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/EconomicEvent'
fromDate:
type: string
toDate:
type: string
total:
type: integer
format: int32
unavailable:
type: boolean
EconomicEvent:
type: object
properties:
event:
type: string
country:
type: string
date:
type: string
impact:
type: string
actual:
type: string
estimate:
type: string
previous:
type: string
unit:
type: string
GetCrudeInventoriesRequest:
type: object
description: GetCrudeInventoriesRequest is the request message for GetCrudeInventories.
GetCrudeInventoriesResponse:
type: object
properties:
weeks:
type: array
items:
$ref: '#/components/schemas/CrudeInventoryWeek'
latestPeriod:
type: string
description: Timestamp of the most recent EIA data point (ISO 8601).
description: GetCrudeInventoriesResponse contains the 8 most recent weeks of US crude oil inventory data.
CrudeInventoryWeek:
type: object
properties:
period:
type: string
description: ISO week period (YYYY-MM-DD, Monday of the EIA report week).
stocksMb:
type: number
format: double
description: Total crude oil stocks in millions of barrels.
weeklyChangeMb:
type: number
format: double
description: |-
Week-over-week change in millions of barrels. Positive = build (bearish), negative = draw (bullish).
Absent for the oldest week when no prior week is available for comparison.
description: CrudeInventoryWeek represents one week of US crude oil stockpile data from EIA WCRSTUS1.
GetNatGasStorageRequest:
type: object
description: GetNatGasStorageRequest is the request message for GetNatGasStorage.
GetNatGasStorageResponse:
type: object
properties:
weeks:
type: array
items:
$ref: '#/components/schemas/NatGasStorageWeek'
latestPeriod:
type: string
description: Timestamp of the most recent EIA data point (ISO 8601).
description: GetNatGasStorageResponse contains the 8 most recent weeks of US natural gas storage data.
NatGasStorageWeek:
type: object
properties:
period:
type: string
description: ISO week period (YYYY-MM-DD, Monday of the EIA report week).
storBcf:
type: number
format: double
description: Working gas in underground storage, Lower-48 States, in Bcf.
weeklyChangeBcf:
type: number
format: double
description: |-
Week-over-week change in Bcf. Positive = build (bearish for gas prices), negative = draw (bullish).
Absent for the oldest week when no prior week is available for comparison.
description: NatGasStorageWeek represents one week of US natural gas working gas storage data from EIA.
GetEcbFxRatesRequest:
type: object
description: GetEcbFxRatesRequest is empty; returns all tracked EUR pairs.
GetEcbFxRatesResponse:
type: object
properties:
rates:
type: array
items:
$ref: '#/components/schemas/EcbFxRate'
updatedAt:
type: string
description: ISO 8601 timestamp of the ECB publication.
seededAt:
type: string
format: int64
description: Unix ms when the data was last seeded.
unavailable:
type: boolean
description: True when Redis key is missing or data is unavailable.
description: GetEcbFxRatesResponse contains the latest ECB reference rates.
EcbFxRate:
type: object
properties:
pair:
type: string
description: Currency pair label, e.g. "EURUSD".
rate:
type: number
format: double
description: Exchange rate (units of quote currency per 1 EUR).
date:
type: string
description: Date of the observation in YYYY-MM-DD format.
change1d:
type: number
format: double
description: 1-day change in rate (absolute).
description: EcbFxRate is a single ECB official reference rate for a currency pair.
GetEurostatCountryDataRequest:
type: object
description: GetEurostatCountryDataRequest requests Eurostat per-country economic data.
GetEurostatCountryDataResponse:
type: object
properties:
countries:
type: object
additionalProperties:
$ref: '#/components/schemas/EurostatCountryEntry'
description: Map of ISO2 country code to economic metrics (e.g. "DE", "FR", "IT").
seededAt:
type: string
format: int64
description: UTC ms timestamp when seed data was written.
unavailable:
type: boolean
description: True when upstream data is unavailable (fallback result).
description: GetEurostatCountryDataResponse contains per-country CPI, unemployment, and GDP growth.
CountriesEntry:
type: object
properties:
key:
type: string
value:
$ref: '#/components/schemas/EurostatCountryEntry'
EurostatCountryEntry:
type: object
properties:
cpi:
$ref: '#/components/schemas/EurostatMetric'
unemployment:
$ref: '#/components/schemas/EurostatMetric'
gdpGrowth:
$ref: '#/components/schemas/EurostatMetric'
description: EurostatCountryEntry holds all available metrics for one EU country.
EurostatMetric:
type: object
properties:
value:
type: number
format: double
description: Numeric value (e.g. 2.3 for 2.3%).
date:
type: string
description: Period string (e.g. "2024-01" for monthly, "2024-Q1" for quarterly).
unit:
type: string
description: Unit of measurement (e.g. "%").
priorValue:
type: number
format: double
description: Prior period value for delta calculation (e.g. previous month/quarter).
hasPrior:
type: boolean
description: True when prior_value is present (proto3 can't distinguish 0 from absent).
description: EurostatMetric holds a single economic metric value for a country.
GetEuGasStorageRequest:
type: object
description: GetEuGasStorageRequest is empty — returns latest EU aggregate snapshot.
GetEuGasStorageResponse:
type: object
properties:
fillPct:
type: number
format: double
description: Current storage fill level as a percentage of working gas volume (0–100).
fillPctChange1d:
type: number
format: double
description: 1-day change in fill percentage (positive = injecting, negative = withdrawing).
gasDaysConsumption:
type: number
format: double
description: Approximate days of consumption remaining at average EU winter drawdown rate.
trend:
type: string
description: 'Current storage trend: "injecting", "withdrawing", or "stable".'
history:
type: array
items:
$ref: '#/components/schemas/EuGasStorageHistoryEntry'
seededAt:
type: string
format: int64
description: UTC ms timestamp when seed data was written.
updatedAt:
type: string
description: Calendar date of the most recent data point (YYYY-MM-DD).
unavailable:
type: boolean
description: True when upstream data is unavailable (fallback result).
description: GetEuGasStorageResponse contains the EU aggregate gas storage snapshot.
EuGasStorageHistoryEntry:
type: object
properties:
date:
type: string
description: Calendar date (YYYY-MM-DD).
fillPct:
type: number
format: double
description: Storage fill level as a percentage of working gas volume capacity.
gasTwh:
type: number
format: double
description: Working gas volume in storage (TWh).
description: EuGasStorageHistoryEntry represents one day of EU aggregate gas storage data.
GetEuYieldCurveRequest:
type: object
description: GetEuYieldCurveRequest fetches the ECB Euro Area AAA sovereign yield curve.
GetEuYieldCurveResponse:
type: object
properties:
data:
$ref: '#/components/schemas/EuYieldCurveData'
unavailable:
type: boolean
description: True if data is not yet available in cache.
description: GetEuYieldCurveResponse contains the latest ECB Euro Area AAA sovereign yield curve.
EuYieldCurveData:
type: object
properties:
date:
type: string
description: Date of the observation (YYYY-MM or YYYY-MM-DD).
rates:
type: object
additionalProperties:
type: number
format: double
description: 'Spot rates by tenor. Keys: "1Y", "2Y", "5Y", "10Y", "20Y", "30Y".'
source:
type: string
description: Data source identifier (e.g. "ecb-aaa").
updatedAt:
type: string
description: ISO 8601 timestamp when this was last seeded.
description: EuYieldCurveData holds a single observation of the ECB Euro Area AAA yield curve.
RatesEntry:
type: object
properties:
key:
type: string
value:
type: number
format: double
GetEuFsiRequest:
type: object
GetEuFsiResponse:
type: object
properties:
latestValue:
type: number
format: double
latestDate:
type: string
label:
type: string
history:
type: array
items:
$ref: '#/components/schemas/EuFsiObservation'
seededAt:
type: string
unavailable:
type: boolean
EuFsiObservation:
type: object
properties:
date:
type: string
value:
type: number
format: double
GetEconomicStressRequest:
type: object
GetEconomicStressResponse:
type: object
properties:
compositeScore:
type: number
format: double
label:
type: string
components:
type: array
items:
$ref: '#/components/schemas/EconomicStressComponent'
seededAt:
type: string
unavailable:
type: boolean
EconomicStressComponent:
type: object
properties:
id:
type: string
label:
type: string
rawValue:
type: number
format: double
score:
type: number
format: double
weight:
type: number
format: double
missing:
type: boolean
GetFaoFoodPriceIndexRequest:
type: object
GetFaoFoodPriceIndexResponse:
type: object
properties:
points:
type: array
items:
$ref: '#/components/schemas/FaoFoodPricePoint'
fetchedAt:
type: string
currentFfpi:
type: number
format: double
momPct:
type: number
format: double
yoyPct:
type: number
format: double
FaoFoodPricePoint:
type: object
properties:
date:
type: string
ffpi:
type: number
format: double
meat:
type: number
format: double
dairy:
type: number
format: double
cereals:
type: number
format: double
oils:
type: number
format: double
sugar:
type: number
format: double
GetOilStocksAnalysisRequest:
type: object
description: GetOilStocksAnalysisRequest is empty — returns the latest global analysis snapshot.
GetOilStocksAnalysisResponse:
type: object
properties:
updatedAt:
type: string
description: UTC ISO-8601 timestamp when this analysis was written.
dataMonth:
type: string
description: 'Data month in YYYY-MM format (source: IEA monthly release).'
ieaMembers:
type: array
items:
$ref: '#/components/schemas/OilStocksAnalysisMember'
belowObligation:
type: array
items:
type: string
description: ISO2 codes of countries currently below the 90-day obligation.
regionalSummary:
$ref: '#/components/schemas/OilStocksRegionalSummary'
unavailable:
type: boolean
description: True when upstream seed data is unavailable (fallback result).
description: GetOilStocksAnalysisResponse contains the IEA oil stocks days-of-cover analysis.
OilStocksAnalysisMember:
type: object
properties:
iso2:
type: string
description: ISO 3166-1 alpha-2 country code.
daysOfCover:
type: integer
format: int32
description: Days of supply cover (absent when country is a net exporter or data anomaly).
netExporter:
type: boolean
description: True when the country is classified as a net exporter by IEA.
belowObligation:
type: boolean
description: True when days_of_cover < 90 (IEA 90-day obligation threshold).
obligationMet:
type: boolean
description: True when the 90-day obligation is met (net exporters always true).
rank:
type: integer
format: int32
description: Rank within the IEA member ranking (1-indexed, net exporters ranked last).
vsObligation:
type: integer
format: int32
description: days_of_cover - 90; absent for net exporters.
description: OilStocksAnalysisMember holds days-of-cover data and obligation status for one IEA member country.
OilStocksRegionalSummary:
type: object
properties:
europe:
$ref: '#/components/schemas/OilStocksRegionalSummaryEurope'
asiaPacific:
$ref: '#/components/schemas/OilStocksRegionalSummaryAsiaPacific'
northAmerica:
$ref: '#/components/schemas/OilStocksRegionalSummaryNorthAmerica'
description: OilStocksRegionalSummary holds regional aggregates for the three IEA regions.
OilStocksRegionalSummaryEurope:
type: object
properties:
avgDays:
type: integer
format: int32
description: Mean days of cover across non-net-exporter European members.
minDays:
type: integer
format: int32
description: Minimum days of cover across non-net-exporter European members.
countBelowObligation:
type: integer
format: int32
description: Count of European members below the 90-day obligation.
description: OilStocksRegionalSummaryEurope aggregates days-of-cover for European IEA members.
OilStocksRegionalSummaryAsiaPacific:
type: object
properties:
avgDays:
type: integer
format: int32
description: Mean days of cover across Asia-Pacific members (AU, JP, KR, NZ).
minDays:
type: integer
format: int32
description: Minimum days of cover across Asia-Pacific members.
countBelowObligation:
type: integer
format: int32
description: Count of Asia-Pacific members below the 90-day obligation.
description: OilStocksRegionalSummaryAsiaPacific aggregates days-of-cover for Asia-Pacific IEA members.
OilStocksRegionalSummaryNorthAmerica:
type: object
properties:
netExporters:
type: integer
format: int32
description: Count of net exporters in North America (CA, MX, US).
avgDays:
type: integer
format: int32
description: Average days of cover for non-exporter North American members (if any).
description: OilStocksRegionalSummaryNorthAmerica aggregates data for North American IEA members.
GetOilInventoriesRequest:
type: object
GetOilInventoriesResponse:
type: object
properties:
crudeWeeks:
type: array
items:
$ref: '#/components/schemas/CrudeInventoryWeekRef'
spr:
$ref: '#/components/schemas/OilInventoriesSprSnapshot'
natGasWeeks:
type: array
items:
$ref: '#/components/schemas/NatGasWeekRef'
euGas:
$ref: '#/components/schemas/OilInventoriesEuGas'
ieaStocks:
$ref: '#/components/schemas/OilInventoriesIeaStocks'
refinery:
$ref: '#/components/schemas/OilInventoriesRefinery'
updatedAt:
type: string
CrudeInventoryWeekRef:
type: object
properties:
period:
type: string
stocksMb:
type: number
format: double
weeklyChangeMb:
type: number
format: double
OilInventoriesSprSnapshot:
type: object
properties:
latestStocksMb:
type: number
format: double
changeWow:
type: number
format: double
weeks:
type: array
items:
$ref: '#/components/schemas/OilInventoriesSprWeek'
OilInventoriesSprWeek:
type: object
properties:
period:
type: string
stocksMb:
type: number
format: double
NatGasWeekRef:
type: object
properties:
period:
type: string
storBcf:
type: number
format: double
weeklyChangeBcf:
type: number
format: double
OilInventoriesEuGas:
type: object
properties:
fillPct:
type: number
format: double
fillPctChange1d:
type: number
format: double
trend:
type: string
history:
type: array
items:
$ref: '#/components/schemas/OilInventoriesEuGasDay'
OilInventoriesEuGasDay:
type: object
properties:
date:
type: string
fillPct:
type: number
format: double
OilInventoriesIeaStocks:
type: object
properties:
dataMonth:
type: string
members:
type: array
items:
$ref: '#/components/schemas/OilInventoriesIeaMember'
europe:
$ref: '#/components/schemas/OilInventoriesRegionStats'
asiaPacific:
$ref: '#/components/schemas/OilInventoriesRegionStats'
northAmerica:
$ref: '#/components/schemas/OilInventoriesRegionStats'
OilInventoriesIeaMember:
type: object
properties:
iso2:
type: string
daysOfCover:
type: number
format: double
netExporter:
type: boolean
belowObligation:
type: boolean
OilInventoriesRegionStats:
type: object
properties:
avgDays:
type: number
format: double
minDays:
type: number
format: double
countBelowObligation:
type: integer
format: int32
OilInventoriesRefinery:
type: object
properties:
inputsMbpd:
type: number
format: double
period:
type: string
GetEnergyCrisisPoliciesRequest:
type: object
properties:
countryCode:
type: string
description: Optional ISO-2 country code filter.
category:
type: string
description: 'Optional category filter: "conservation" or "consumer_support".'
description: GetEnergyCrisisPoliciesRequest allows optional filtering by country or category.
GetEnergyCrisisPoliciesResponse:
type: object
properties:
source:
type: string
description: Source attribution.
sourceUrl:
type: string
description: Source URL.
context:
type: string
description: Context description.
policies:
type: array
items:
$ref: '#/components/schemas/EnergyCrisisPolicy'
updatedAt:
type: string
description: UTC ISO-8601 timestamp when this data was last updated.
unavailable:
type: boolean
description: True when upstream seed data is unavailable (fallback result).
description: GetEnergyCrisisPoliciesResponse contains energy crisis policy data from the IEA tracker.
EnergyCrisisPolicy:
type: object
properties:
country:
type: string
description: Country name.
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code.
category:
type: string
description: 'Policy category: "conservation" or "consumer_support".'
sector:
type: string
description: 'Affected sector: transport, buildings, industry, electricity, agriculture, general.'
measure:
type: string
description: Description of the policy measure.
dateAnnounced:
type: string
description: Date announced in ISO-8601 (YYYY-MM-DD) format.
status:
type: string
description: 'Status of the policy: active, planned, or ended.'
description: EnergyCrisisPolicy represents a single government policy response to the 2026 energy crisis.
Reference in New Issue View Git Blame Copy Permalink