{"openapi":"3.0.3","info":{"title":"Aether-X Port Congestion Oracle","description":"Port congestion reference signals for global trade, supply chain and quantitative finance.\n\n**IMPORTANT · Data integrity notice**: every response includes `data_source`, `data_source_label` and `as_of`.\nBrazilian ports (BRSSZ, BRPNG, BRRIO, BRNIT, BRITG) serve live line-ups: `data_source=\"live:appa+santos+lachmann\"` (BRSSZ/BRPNG) and `data_source=\"live:portosrio_silog\"` (BRRIO/BRNIT/BRITG). The remaining ports\nserve a **static reference seed**: `data_source=\"static_reference_seed\"` means the value is a seeded baseline, not a\nlive measurement. The 24/48/72h trend is a `synthetic_projection`, not a live forecast. Do not treat seed numbers as\nreal-time field data.\n\n**The signal** — `GET /v1/port-risk?port_id=BRSSZ` returns:\n\n| Field | Meaning |\n|-------|---------|\n| `congestion_score` | Normalized 0.0–1.0 reference congestion level (seeded) |\n| `eta_delay_days` | Reference delay applied to incoming vessels |\n| `waiting_vessels` | Reference ships anchored or queued |\n| `freight_volatility_index` | Pressure indicator for freight pricing |\n| `estimated_daily_demurrage_usd` | Estimated daily demurrage (USD) for a vessel queued at the port |\n| `data_source` | Always `static_reference_seed` until live telemetry is connected |\n| `as_of` | Timestamp of the seed (not a live refresh) |\n\n**Trend (24h/48h/72h)** — `GET /v1/port-trend?port_id=BRSSZ` returns a **synthetic** projection with a `trend` label: `acelerando`, `estável` or `descongestionando`.\n\n**Free tier** — $0.00, no credit card required. Pay-as-you-go beyond the free tier at $0.02 per query.\n\n**Other ways to consume it**\n- Python SDK: `pip install aetherx-oracle`\n- MCP server for AI agents: `uvx aetherx-mcp` (or the hosted `/mcp` endpoint) — tools: `get_port_risk`, `get_ports_risk`, `get_port_trend`\n\n**Coverage** — 19 ports: BRSSZ, BRPNG, BRRIO, BRNIT, BRITG, CNSHA, CNNGB, CNTAO, SGSIN, NLRTM, USLAX, USNYC, DEHAM, MPTNG, AEDXB, KRPUS, GBLGP, ZACPT, MXZLO. Unknown ports return a global statistical estimate (`country=\"Global\"`).\n\nSignals are provided \"AS IS\" and do not constitute investment advice.\n","termsOfService":"https://aetherx.aether-grid.io/terms","contact":{"name":"Aether-X","url":"https://aetherx.aether-grid.io/","email":"contato@aether-grid.io"},"license":{"name":"Machine-to-Machine Data Distribution (see /terms)","url":"https://aetherx.aether-grid.io/terms"},"version":"0.2.1","x-logo":{"url":"https://raw.githubusercontent.com/belegante-byte/aetherx-mcp/main/assets/logo.png","altText":"Aether-X Port Congestion Oracle"}},"servers":[{"url":"https://aetherx.aether-grid.io","description":"Production (Railway)"}],"paths":{"/v1/port-risk":{"get":{"tags":["Port Risk"],"summary":"Get port congestion risk for a single port","description":"Returns the reference congestion signal for a single global port: `congestion_score` (0.0-1.0), `eta_delay_days`, `waiting_vessels`, `freight_volatility_index` and the estimated `estimated_daily_demurrage_usd`. Every response includes `data_source` (`static_reference_seed` until live telemetry is connected) and `as_of` (seed timestamp, not a live refresh). Coverage: 19 ports (BRSSZ, CNSHA, CNTAO, NLRTM, ...). Unknown ports fall back to a global statistical estimate with `country=\"Global\"`. Requests are protected by the RapidAPI proxy secret and must send the `X-RapidAPI-Proxy-Secret` header.","operationId":"get_port_risk_v1_port_risk_get","parameters":[{"name":"port_id","in":"query","required":true,"schema":{"type":"string","description":"UN/LOCODE of the port, e.g. BRSSZ (Santos), CNSHA (Shanghai), NLRTM (Rotterdam).","examples":["BRSSZ"],"title":"Port Id"},"description":"UN/LOCODE of the port, e.g. BRSSZ (Santos), CNSHA (Shanghai), NLRTM (Rotterdam)."}],"responses":{"200":{"description":"The current reference signal for the requested port.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortRiskResponse"},"example":{"port_id":"BRSSZ","port_name":"Santos","country":"Brasil","congestion_score":0.33,"eta_delay_days":0.2,"waiting_vessels":0,"freight_volatility_index":0.4,"estimated_daily_demurrage_usd":45200,"updated_at":"2026-09-19 01:34:42","as_of":"2026-09-19 01:34:42","data_source":"live:santos+santos_painel","data_source_label":"Live line-up from Porto de Santos + Painel de operações de Santos.","live_detail":"{\"ao_largo\": 0, \"esperados\": 0, \"atracados\": 591, \"programados\": 135}","validation":{"source":"antaq_estatistico_aquaviario","ano":2026,"mes":"jan","n_atracacoes":500,"n_com_imo":491,"espera_atracacao_h_avg":51.4,"espera_atracacao_h_med":10.2,"espera_atracacao_h_p90":151.1,"atracado_h_avg":50.1,"estadia_h_avg":101.3,"validado_em":"2026-09-19 01:49:06"},"live":{"ao_largo":0,"esperados":0,"atracados":591,"programados":135}}}}},"401":{"description":"Missing or invalid X-RapidAPI-Proxy-Secret header.","content":{"application/json":{"example":{"detail":"Missing or invalid X-RapidAPI-Proxy-Secret header."}}}}}}},"/v1/port-trend":{"get":{"tags":["Port Risk"],"summary":"Get port risk trend","description":"Returns the 24h, 48h and 72h congestion projections for a single global port, with a `trend` label (`acelerando`, `estável` or `descongestionando`). Each projection point includes `congestion_score`, `eta_delay_days` and the estimated `estimated_daily_demurrage_usd`. NOTE: the projection is `synthetic_projection` (derived from the static reference seed), not a live forecast. Requests are protected by the RapidAPI proxy secret and must send the `X-RapidAPI-Proxy-Secret` header.","operationId":"get_port_trend_v1_port_trend_get","parameters":[{"name":"port_id","in":"query","required":true,"schema":{"type":"string","description":"UN/LOCODE of the port, e.g. BRSSZ (Santos), CNSHA (Shanghai), NLRTM (Rotterdam).","examples":["BRSSZ"],"title":"Port Id"},"description":"UN/LOCODE of the port, e.g. BRSSZ (Santos), CNSHA (Shanghai), NLRTM (Rotterdam)."}],"responses":{"200":{"description":"The 24h, 48h and 72h congestion projections for the requested port.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortTrendResponse"},"example":{"port_id":"BRSSZ","port_name":"Santos","country":"Brasil","trend":"acelerando","congestion_score":0.33,"projection":{"h24":{"congestion_score":0.35,"eta_delay_days":0.21,"estimated_daily_demurrage_usd":46000},"h48":{"congestion_score":0.35,"eta_delay_days":0.21,"estimated_daily_demurrage_usd":46000},"h72":{"congestion_score":0.36,"eta_delay_days":0.22,"estimated_daily_demurrage_usd":46400}},"updated_at":"2026-09-19 01:34:42","as_of":"2026-09-19 01:34:42","data_source":"synthetic_projection","data_source_label":"Synthetic projection from static reference seed (not a live forecast)."}}}},"401":{"description":"Missing or invalid X-RapidAPI-Proxy-Secret header.","content":{"application/json":{"example":{"detail":"Missing or invalid X-RapidAPI-Proxy-Secret header."}}}}}}},"/v1/ports-risk":{"get":{"tags":["Port Risk"],"summary":"Get congestion risk for multiple ports in one call","description":"Returns the congestion signals for up to 20 ports in a single request, preserving the order of the `port_ids` (comma-separated UN/LOCODEs). Unknown ports fall back to the global statistical estimate. Requests are protected by the RapidAPI proxy secret and must send the `X-RapidAPI-Proxy-Secret` header.","operationId":"get_ports_risk_v1_ports_risk_get","parameters":[{"name":"port_ids","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated UN/LOCODEs, e.g. BRSSZ,CNSHA,NLRTM (max 20).","examples":["BRSSZ,CNSHA,NLRTM"],"title":"Port Ids"},"description":"Comma-separated UN/LOCODEs, e.g. BRSSZ,CNSHA,NLRTM (max 20)."}],"responses":{"200":{"description":"The congestion signals, one per requested port.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortsRiskResponse"},"example":{"results":[{"port_id":"BRSSZ","port_name":"Santos","country":"Brasil","congestion_score":0.33,"eta_delay_days":0.2,"waiting_vessels":0,"freight_volatility_index":0.4,"estimated_daily_demurrage_usd":45200,"updated_at":"2026-09-19 01:34:42","as_of":"2026-09-19 01:34:42","data_source":"live:santos+santos_painel","data_source_label":"Live line-up from Porto de Santos + Painel de operações de Santos.","live_detail":"{\"ao_largo\": 0, \"esperados\": 0, \"atracados\": 591, \"programados\": 135}","validation":{"source":"antaq_estatistico_aquaviario","ano":2026,"mes":"jan","n_atracacoes":500,"n_com_imo":491,"espera_atracacao_h_avg":51.4,"espera_atracacao_h_med":10.2,"espera_atracacao_h_p90":151.1,"atracado_h_avg":50.1,"estadia_h_avg":101.3,"validado_em":"2026-09-19 01:49:06"},"live":{"ao_largo":0,"esperados":0,"atracados":591,"programados":135}},{"port_id":"CNSHA","port_name":"Shanghai","country":"China","congestion_score":0.72,"eta_delay_days":1.5,"waiting_vessels":18,"freight_volatility_index":0.38,"estimated_daily_demurrage_usd":60800,"updated_at":"2026-09-19 00:44:19","as_of":"2026-09-19 00:44:19","data_source":"static_reference_seed","data_source_label":"Static reference data (no live telemetry connected).","live_detail":null,"validation":null}]}}}},"400":{"description":"More than 20 ports requested in port_ids.","content":{"application/json":{"example":{"detail":"port_ids accepts at most 20 ports per call."}}}},"401":{"description":"Missing or invalid X-RapidAPI-Proxy-Secret header.","content":{"application/json":{"example":{"detail":"Missing or invalid X-RapidAPI-Proxy-Secret header."}}}}}}}},"components":{"schemas":{"PortRiskResponse":{"properties":{"port_id":{"type":"string","title":"Port Id"},"port_name":{"type":"string","title":"Port Name"},"country":{"type":"string","title":"Country"},"congestion_score":{"type":"number","title":"Congestion Score"},"eta_delay_days":{"type":"number","title":"Eta Delay Days"},"waiting_vessels":{"type":"integer","title":"Waiting Vessels"},"freight_volatility_index":{"type":"number","title":"Freight Volatility Index"},"estimated_daily_demurrage_usd":{"type":"integer","title":"Estimated Daily Demurrage Usd"},"updated_at":{"type":"string","title":"Updated At"},"as_of":{"type":"string","title":"As Of"},"data_source":{"type":"string","title":"Data Source"},"data_source_label":{"type":"string","title":"Data Source Label"},"live_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Live Detail"},"live":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Live"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"}},"type":"object","required":["port_id","port_name","country","congestion_score","eta_delay_days","waiting_vessels","freight_volatility_index","estimated_daily_demurrage_usd","updated_at","as_of","data_source","data_source_label"],"title":"PortRiskResponse","examples":[{"as_of":"2026-09-19 01:34:42","congestion_score":0.33,"country":"Brasil","data_source":"live:santos+santos_painel","data_source_label":"Live line-up from Porto de Santos + Painel de operações de Santos.","estimated_daily_demurrage_usd":45200,"eta_delay_days":0.2,"freight_volatility_index":0.4,"live":{"ao_largo":0,"atracados":591,"esperados":0,"programados":135},"live_detail":"{\"ao_largo\": 0, \"esperados\": 0, \"atracados\": 591, \"programados\": 135}","port_id":"BRSSZ","port_name":"Santos","updated_at":"2026-09-19 01:34:42","validation":{"ano":2026,"atracado_h_avg":50.1,"espera_atracacao_h_avg":51.4,"espera_atracacao_h_med":10.2,"espera_atracacao_h_p90":151.1,"estadia_h_avg":101.3,"mes":"jan","n_atracacoes":500,"n_com_imo":491,"source":"antaq_estatistico_aquaviario","validado_em":"2026-09-19 01:49:06"},"waiting_vessels":0}]},"PortTrendResponse":{"properties":{"port_id":{"type":"string","title":"Port Id"},"port_name":{"type":"string","title":"Port Name"},"country":{"type":"string","title":"Country"},"trend":{"type":"string","title":"Trend"},"congestion_score":{"type":"number","title":"Congestion Score"},"projection":{"additionalProperties":{"$ref":"#/components/schemas/TrendPoint"},"type":"object","title":"Projection"},"updated_at":{"type":"string","title":"Updated At"},"as_of":{"type":"string","title":"As Of"},"data_source":{"type":"string","title":"Data Source"},"data_source_label":{"type":"string","title":"Data Source Label"}},"type":"object","required":["port_id","port_name","country","trend","congestion_score","projection","updated_at","as_of","data_source","data_source_label"],"title":"PortTrendResponse","examples":[{"as_of":"2026-09-19 01:34:42","congestion_score":0.33,"country":"Brasil","data_source":"synthetic_projection","data_source_label":"Synthetic projection from static reference seed (not a live forecast).","port_id":"BRSSZ","port_name":"Santos","projection":{"h24":{"congestion_score":0.35,"estimated_daily_demurrage_usd":46000,"eta_delay_days":0.21},"h48":{"congestion_score":0.35,"estimated_daily_demurrage_usd":46000,"eta_delay_days":0.21},"h72":{"congestion_score":0.36,"estimated_daily_demurrage_usd":46400,"eta_delay_days":0.22}},"trend":"acelerando","updated_at":"2026-09-19 01:34:42"}]},"PortsRiskResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PortRiskResponse"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"PortsRiskResponse","examples":[{"results":[{"as_of":"2026-09-19 01:34:42","congestion_score":0.33,"country":"Brasil","data_source":"live:santos+santos_painel","data_source_label":"Live line-up from Porto de Santos + Painel de operações de Santos.","estimated_daily_demurrage_usd":45200,"eta_delay_days":0.2,"freight_volatility_index":0.4,"live":{"ao_largo":0,"atracados":591,"esperados":0,"programados":135},"live_detail":"{\"ao_largo\": 0, \"esperados\": 0, \"atracados\": 591, \"programados\": 135}","port_id":"BRSSZ","port_name":"Santos","updated_at":"2026-09-19 01:34:42","validation":{"ano":2026,"atracado_h_avg":50.1,"espera_atracacao_h_avg":51.4,"espera_atracacao_h_med":10.2,"espera_atracacao_h_p90":151.1,"estadia_h_avg":101.3,"mes":"jan","n_atracacoes":500,"n_com_imo":491,"source":"antaq_estatistico_aquaviario","validado_em":"2026-09-19 01:49:06"},"waiting_vessels":0},{"as_of":"2026-09-19 00:44:19","congestion_score":0.72,"country":"China","data_source":"static_reference_seed","data_source_label":"Static reference data (no live telemetry connected).","estimated_daily_demurrage_usd":60800,"eta_delay_days":1.5,"freight_volatility_index":0.38,"port_id":"CNSHA","port_name":"Shanghai","updated_at":"2026-09-19 00:44:19","waiting_vessels":18}]}]},"TrendPoint":{"properties":{"congestion_score":{"type":"number","title":"Congestion Score"},"eta_delay_days":{"type":"number","title":"Eta Delay Days"},"estimated_daily_demurrage_usd":{"type":"integer","title":"Estimated Daily Demurrage Usd"}},"type":"object","required":["congestion_score","eta_delay_days","estimated_daily_demurrage_usd"],"title":"TrendPoint"}}},"tags":[{"name":"Port Risk","description":"Predictive congestion, ETA delay and freight volatility signals per port."}]}