DATASET API · REST · JSON · TIME SERIES
Programmatic access to satellite-derived carbon datasets.
8 institutional datasets via REST API. Each dataset accessible as a time series at its own dedicated endpoint. Bearer token auth, weekly updates.
Base URL:
https://api.satclimate.ioAuth: Bearer token in Authorization header
Format: JSON · Time series · ISO week / date indexed
Rate limit: 10,000 requests/month (Enterprise: unlimited)
Quick Start
1
Get API Key
Subscribe to a SatClimate plan to receive your API credentials.
2
Set Authorization
Add your Bearer token to the Authorization header in every request.
3
Fetch Signals
Call /api/v1/datasets or /signals to get carbon market intelligence.
API Reference
All dataset endpoints return time-series JSON with a data array and meta object. Signals are derived outputs from the dataset layer.
📊 Dataset Endpoints (Primary)
Industrial Production Nowcast — satellite-derived steel, cement, chemical activity indices by region. Weekly time series.
// Example response
{
"data": [
{
"date": "2026-W11",
"region": "EU-27",
"steel_activity_index": 68,
"cement_activity_index": 72,
"chemical_activity_index": 61,
"industrial_production_score": 67
}
],
"meta": {
"records": 52,
"coverage": "EU-27, China, Korea, Turkey, India",
"update_freq": "weekly"
}
}🔍 Query Parameters
📡 Signal Endpoints (Derived)
🏛️ Market Model Endpoints
Code Examples
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
url = 'https://api.satclimate.io/api/v1/datasets/industrial_activity'
params = {'from': '2026-W01', 'to': '2026-W11', 'region': 'EU-27'}
response = requests.get(url, headers=headers, params=params)
data = response.json()['data']
for record in data:
print(f"{record['date']} | {record['region']} | steel={record['steel_activity_index']} | score={record['industrial_production_score']}")Authentication
Bearer Token
Include your API key as a Bearer token in the Authorization header:
Authorization: Bearer sk_live_xxxxxxxxxxxxx
Find your API key in your SatClimate workspace under Settings → API Keys.
Response Format
All responses are returned as JSON. Successful responses include HTTP 200 status.
{
"status": "success",
"data": {
// Endpoint-specific data
},
"timestamp": "2026-03-16T10:30:00Z",
"request_id": "req_xxx"
}OpenAPI 3.1 · Machine-Readable · Institutional Grade
OpenAPI Specification
Machine-readable API contract for Bloomberg B-PIPE, Refinitiv Eikon, quant team integrations, and procurement audits. All signal fields, enums, and governance annotations are defined. Schema version: 1.5.
Self-declared. Not yet registered on APIs.guru or SwaggerHub. Registration in progress.
Fail-closed declared
503 on Redis unavailability — never fail-open
Deprecation policy
60-day notice period + x-deprecated annotation
Deterministic confidence
No random variance — formula published verbatim
satclimate-openapi-1.5.json Swagger Editor
{
"openapi": "3.1.0",
"info": {
"title": "SatClimate Intelligence Platform API",
"version": "4.1.0",
"description": "Satellite-derived environmental intelligence and carbon market signals for institutional consumers. All signals include provenance_hash, schema_version, observed_at, generated_at, signal_mode, and confidence_methodology for SR 11-7 and procurement audit alignment.",
"contact": {
"name": "SatClimate API Support",
"email": "amin@carbonaa.net",
"url": "https://sat.carbonaa.net/SatClimateContactPage"
},
"license": {
"name": "Commercial — see Terms of Engine",
"url": "https://sat.carbonaa.net/SatClimateTerms"
},
"x-schema-governance": {
"schema_version": "1.5",
"backward_compatibility": "Fields will not be removed or renamed within a major version. New optional fields may be added. Deprecated fields will be flagged with x-deprecated: true for 2 full release cycles before removal.",
"deprecation_policy": "Deprecated fields carry x-deprecated and x-remove-after annotations. Minimum 60-day notice period before field removal.",
"content_type": "application/json;version=1.5",
"fail_closed_note": "Quota enforcement uses Redis atomic operations. If Redis is unavailable, the API returns 503 (not 200). This is intentional: the system fails closed, never open."
}
},
"servers": [
{
"url": "https://sat.carbonaa.net",
"description": "Production — Live data. API keys required."
}
],
"security": [
{
"ApiKeyHeader": []
}
],
"components": {
"securitySchemes": {
"ApiKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "API key issued at subscription. SHA-256 hashed at rest. Rotate every 90 days via workspace."
}
},
"schemas": {
"EnvironmentalSignal": {
"type": "object",
"required": [
"signal_id",
"schema_version",
"signal_type",
"region",
"signal_value",
"anomaly_severity",
"confidence_score",
"signal_mode",
"fetch_status",
"data_gap_flag",
"observed_at",
"fetched_at",
"data_source",
"data_sources",
"provenance_hash"
],
"properties": {
"signal_id": {
"type": "string",
"example": "sig_env-1746530000000_temperature_anomaly_0",
"description": "Unique signal identifier. Format: sig_{requestId}_{signal_type}_{index}"
},
"schema_version": {
"type": "string",
"example": "1.0",
"description": "Schema version. Consumers should validate against this field."
},
"signal_class": {
"type": "string",
"enum": [
"environmental_observation"
],
"description": "Signal taxonomy class for programmatic routing."
},
"signal_type": {
"type": "string",
"enum": [
"temperature_anomaly",
"soil_moisture_deficit",
"thermal_anomaly",
"atmospheric_emissions",
"seismic_activity"
],
"description": "Type of environmental observation."
},
"region": {
"type": "string",
"example": "europe"
},
"signal_value": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Normalized signal strength 0-1."
},
"anomaly_severity": {
"type": "string",
"enum": [
"low",
"moderate",
"high",
"critical",
"unknown"
],
"description": "unknown = data_gap_flag is true."
},
"confidence_score": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "0 when data_gap_flag is true. Otherwise 79-97 depending on source plan."
},
"signal_mode": {
"type": "string",
"enum": [
"live",
"cached",
"fallback",
"unavailable"
],
"description": "Freshness state. Never omitted."
},
"fetch_status": {
"type": "string",
"enum": [
"ok",
"error",
"timeout"
],
"description": "Upstream data source fetch result."
},
"data_gap_flag": {
"type": "boolean",
"description": "true = upstream fetch failed. confidence_score is 0 when true. Never trust anomaly_severity when true."
},
"fallback_reason": {
"type": "string",
"nullable": true,
"description": "Populated when signal_mode is fallback or unavailable."
},
"observed_at": {
"type": "string",
"format": "date-time",
"description": "Start of the observation window (not fetch time)."
},
"fetched_at": {
"type": "string",
"format": "date-time",
"description": "When this function fetched from upstream source."
},
"data_source": {
"type": "string",
"description": "Primary upstream source. Deprecated — use data_sources[] instead."
},
"data_sources": {
"type": "array",
"items": {
"type": "string"
},
"description": "Canonical array of upstream sources. Machine-parseable."
},
"source_reliability_class": {
"type": "string",
"enum": [
"tier1_exchange",
"tier2_satellite",
"tier3_model"
]
},
"provenance_hash": {
"type": "string",
"description": "FNV-1a deterministic hash of signal_type|region|signal_value|anomaly_severity|fetched_at|schema_version. Enables tamper detection."
},
"raw": {
"type": "object",
"description": "Intermediate derivation values. All model_inputs exposed for reproducibility."
},
"trend": {
"type": "string",
"enum": [
"deteriorating",
"stable",
"improving",
"unknown"
]
}
}
},
"ContextualSignal": {
"type": "object",
"required": [
"signal_id",
"schema_version",
"signal_class",
"asset_class",
"market",
"commodity",
"region",
"signal_direction",
"confidence_score",
"confidence_methodology",
"confidence_factors",
"impact_pct",
"timeframe",
"observed_at",
"generated_at",
"model_version",
"signal_mode",
"provenance_hash",
"data_sources",
"disclaimer"
],
"properties": {
"signal_id": {
"type": "string",
"example": "sig_sc-1746530000000_eex"
},
"schema_version": {
"type": "string",
"example": "1.5"
},
"signal_class": {
"type": "string",
"enum": [
"directional_financial"
]
},
"asset_class": {
"type": "string",
"enum": [
"carbon_permit",
"energy_commodity",
"agricultural_commodity",
"cross_asset_environmental_beta"
]
},
"market": {
"type": "string",
"enum": [
"EEX",
"ICE",
"DCE",
"TTF",
"NYMEX",
"Brent",
"CBOT",
"Euronext"
]
},
"commodity": {
"type": "string",
"enum": [
"eua",
"cca",
"natural_gas",
"brent_crude",
"crude_oil",
"power",
"wheat",
"corn",
"soybeans",
"rapeseed",
"iron_ore"
]
},
"region": {
"type": "string",
"example": "Central & Western Europe"
},
"signal_direction": {
"type": "string",
"enum": [
"bullish",
"bearish",
"neutral",
"elevated",
"low"
]
},
"impact_pct": {
"type": "number",
"description": "Volatility-anchored directional impact estimate. Formula: weekly_1sigma × probability_multiplier × segment_sensitivity. NOT a price foresight."
},
"timeframe": {
"type": "string",
"example": "2-6w"
},
"timeframe_days_min": {
"type": "integer"
},
"timeframe_days_max": {
"type": "integer"
},
"confidence_score": {
"type": "integer",
"minimum": 42,
"maximum": 94,
"description": "Deterministic. Formula: base(segment) + 0.5×|riskScore-50| + neutral_penalty(-8). No random variance."
},
"confidence_methodology": {
"type": "string",
"description": "Verbatim formula published in every response."
},
"confidence_factors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Derivation components: segment_base, distance_bonus, neutral_penalty."
},
"observed_at": {
"type": "string",
"format": "date-time",
"description": "Latest satellite pass boundary (6h UTC intervals: 04:00, 10:00, 16:00, 22:00)."
},
"generated_at": {
"type": "string",
"format": "date-time",
"description": "When this signal was generated server-side."
},
"model_version": {
"type": "string",
"example": "contextual_signals_v1.5"
},
"generated_by_engine": {
"type": "string",
"example": "contextual_signals_v1.5"
},
"signal_mode": {
"type": "string",
"enum": [
"live",
"cached",
"fallback"
]
},
"fallback_reason": {
"type": "string",
"nullable": true
},
"data_sources": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_hash": {
"type": "string",
"description": "FNV-1a of direction|confidence|observed_at|market|commodity|schema_version."
},
"model_inputs": {
"type": "object",
"description": "All derivation parameters for signal reconstruction: scenario, llm_probability_score_raw, market_mod, seasonal_adj, base_prob_used, blended_prob_final."
},
"actionability_class": {
"type": "string",
"enum": [
"actionable",
"watch",
"scanner"
]
},
"color_semantic": {
"type": "string",
"enum": [
"green",
"amber",
"red",
"grey"
],
"description": "Canonical UI rendering hint. grey = fallback signal."
},
"disclaimer": {
"type": "string",
"description": "Mandatory disclaimer. impact_pct is not a price foresight. Signals require human interpretation. No autonomous execution."
},
"key_driver": {
"type": "string"
},
"signal_interpretation": {
"type": "string"
},
"recommended_action": {
"type": "string"
},
"watch_indicator": {
"type": "string",
"nullable": true,
"description": "Present only on neutral signals."
},
"blend_weights": {
"type": "object",
"nullable": true,
"description": "Present only for hedge_fund segment."
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
},
"paths": {
"/functions/satclimateDataAPI": {
"post": {
"operationId": "getEnvironmentalSignals",
"summary": "Environmental Intelligence API",
"description": "Returns live environmental signals from NASA FIRMS, Open-Meteo (ERA5), OpenAQ, and USGS. Each signal includes provenance_hash, data_gap_flag, signal_mode, and confidence_score. data_gap_flag=true when upstream fetch failed — never treat those signals as authoritative.",
"tags": [
"Environmental Signals"
],
"x-rate-limit": "Monthly quota enforced via Redis atomic operations. If Redis is unavailable, returns 503 (fail-closed).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"api_key": {
"type": "string",
"description": "API key (or pass via X-API-Key header)"
},
"signal_type": {
"type": "string",
"enum": [
"all",
"temperature_anomaly",
"soil_moisture_deficit",
"thermal_anomaly",
"atmospheric_emissions",
"seismic_activity"
],
"default": "all"
},
"region": {
"type": "string",
"enum": [
"europe",
"north_america",
"middle_east",
"south_asia",
"southeast_asia",
"africa",
"latin_america",
"global"
],
"default": "europe"
}
}
},
"example": {
"signal_type": "all",
"region": "europe"
}
}
}
},
"responses": {
"200": {
"description": "Environmental signals returned. Check data_gap_flag on each signal — true means upstream was unavailable.",
"headers": {
"Content-Type": {
"schema": {
"type": "string",
"example": "application/json;version=1.0"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "success"
},
"meta": {
"type": "object",
"description": "Includes region, fetched_at, signal_count, api_version, schema_version, data_gap_count, sandbox."
},
"composite": {
"type": "object",
"description": "crisis_risk_level, avg_signal_strength, critical_signals, high_signals."
},
"signals": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvironmentalSignal"
}
}
}
}
}
}
},
"400": {
"description": "Invalid region or signal_type."
},
"401": {
"description": "Missing API key."
},
"403": {
"description": "Invalid or inactive API key."
},
"429": {
"description": "Monthly quota exceeded."
},
"503": {
"description": "Redis quota engine unavailable. System is fail-closed — retry after 10s.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"example": 10
}
}
}
}
}
}
},
"/functions/contextualSignalsAPI": {
"post": {
"operationId": "getContextualSignal",
"summary": "Contextual Market Intelligence Signals API",
"description": "Returns segment-specific directional signals for carbon, energy, and agricultural markets. Confidence scores are deterministic (no random variance). All signals include model_inputs for reproducibility. Invalid segment/market/commodity combinations return 400 — semantic integrity is enforced server-side.",
"tags": [
"Market Signals"
],
"x-rate-limit": "Redis circuit breaker — fail-closed. Redis unavailable → 503. Monthly + burst quotas enforced atomically.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"segment": {
"type": "string",
"enum": [
"carbon_trader",
"energy_trader",
"ag_food_trader",
"hedge_fund"
]
},
"market": {
"type": "string",
"enum": [
"EEX",
"ICE",
"DCE",
"TTF",
"NYMEX",
"Brent",
"CBOT",
"Euronext"
]
},
"commodity": {
"type": "string",
"enum": [
"eua",
"cca",
"natural_gas",
"brent_crude",
"crude_oil",
"power",
"wheat",
"corn",
"soybeans",
"rapeseed",
"iron_ore"
]
},
"format": {
"type": "string",
"enum": [
"json",
"csv",
"webhook"
],
"default": "json"
}
}
},
"example": {
"segment": "carbon_trader",
"market": "EEX",
"commodity": "eua",
"format": "json"
}
}
}
},
"responses": {
"200": {
"description": "Signal generated. schema_version: 1.5. All 24 mandatory fields present.",
"headers": {
"Content-Type": {
"schema": {
"type": "string",
"example": "application/json;version=1.5"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "ok"
},
"data": {
"$ref": "#/components/schemas/ContextualSignal"
},
"meta": {
"type": "object",
"description": "schema_version, signal_mode, next_update, available_formats, usage."
}
}
}
}
}
},
"400": {
"description": "Invalid segment, market, commodity, or segment/market mismatch. Response includes valid values list."
},
"401": {
"description": "Missing or invalid API key."
},
"429": {
"description": "Monthly quota or burst rate limit exceeded."
},
"503": {
"description": "Redis quota/burst engine unavailable. Fail-closed — retry after 10s."
}
}
}
}
},
"tags": [
{
"name": "Environmental Signals",
"description": "NASA FIRMS, Open-Meteo ERA5, OpenAQ, USGS — live environmental observations with data gap transparency."
},
{
"name": "Market Signals",
"description": "Segment-specific directional signals for carbon, energy, and agricultural markets. Confidence is deterministic, provenance is traceable."
}
]
}To validate: paste the JSON above into editor.swagger.io. Registration on APIs.guru and SwaggerHub is in progress.
Need Help?
📧
API Support
Contact us for questions
📊
Status Page
Check system status and incidents
🔗
Webhook Setup
Configure webhooks to receive signal updates in real-time
