API y MCP

Sin API key. Los mismos datos que alimentan el dashboard, en JSON.

• GET/v1/ops

  Cola oficial del Canal según datos oficiales de la ACP: lectura actual por categoría de buque, proyecciones a 24 y 48 horas, y serie histórica de hasta 60 filas diarias.

  {
    "latest": {
      "date": "2026-06-09",
      "queue_total": 60,
      "queue_neopanamax": 22,
      "queue_panamax_plus": 9,
      "queue_super": 14,
      "queue_regular": 15,
      "queue_proj_24h": 58,
      "queue_proj_48h": 55,
      "arrivals_total": 31,
      "transits_total": 34
    },
    "history": [ /* … */ ]
  }

• GET/v1/lake

  Nivel del lago Gatún (y Alhajuela cuando está disponible), últimos 60 días. Cota en pies sobre el nivel del mar.

  {
    "levels": [
      { "date": "2026-06-08", "gatun_ft": 85.17, "alhajuela_ft": 218.43 },
      { "date": "2026-06-07", "gatun_ft": 85.21, "alhajuela_ft": 218.51 }
    ]
  }

• GET/v1/draft

  Calado máximo autorizado vigente en las esclusas neopanamax, extraído del último advisory de calado de la ACP, con fecha de vigencia y enlace al documento de origen. max_draft_ft es null cuando no hay restricción publicada.

  {
    "max_draft_ft": 50.0,
    "advisory_number": "ADV-12-2026",
    "effective_date": "2026-05-28",
    "source_url": "https://pancanal.com/…"
  }

• GET/v1/advisories?limit=25

  Advisories de la ACP estructurados: número, tipo de documento, nivel de impacto y resúmenes propios en español e inglés, con enlace al documento oficial.

  {
    "advisories": [
      {
        "advisory_number": "ADV-29-2025",
        "doc_type": "advisory",
        "impact_level": "high",
        "summary_es": "Reducción temporal de tránsitos en…",
        "summary_en": "Temporary transit reduction at…",
        "source_url": "https://pancanal.com/…"
      }
    ]
  }

• GET/v1/pulse?limit=30

  Pulso noticioso del Canal: titulares estructurados con categoría, severidad, score y resúmenes propios en español e inglés, con enlace a la fuente original. Filtra con ?categoria= y ?severidad=.

  {
    "items": [
      {
        "title": "Panama Canal adjusts booking slots…",
        "source": "gCaptain",
        "published": "2026-06-09T14:02:00Z",
        "categoria": "tarifas-slots",
        "severidad": "watch",
        "score": 72,
        "resumen_es": "La ACP ajusta los cupos de reserva…",
        "resumen_en": "The ACP adjusts booking slots…",
        "url": "https://…"
      }
    ]
  }

• GET/v1/slots

  Utilización del sistema de reservas: cupos ofrecidos, cupos tomados y porcentaje de utilización por ventana (d7/d30/d90/d365) y categoría de buque, con historia de la ventana de 30 días.

  {
    "as_of": "2026-06-09",
    "windows": [
      { "window": "d30", "category": "neopanamax",
        "slots_total": 310, "slots_booked": 287, "utilization_pct": 92.6 }
    ],
    "history": [ { "as_of": "2026-06-02", "utilization_d30_pct": 90.1 } ]
  }

• GET/v1/ranking

  Top de clientes del Canal según el ranking mensual oficial de la ACP: posición, cliente y movimiento frente al mes anterior. La vista pública es un teaser; la serie completa vive en el tier Pro.

  {
    "month": "2026-05",
    "top": [
      { "rank": 1, "client": "…", "weight": 18.4, "prev_rank": 2, "delta": 1 }
    ]
  }

• GET/v1/chokepoints · /v1/chokepoints?id=hormuz

  Los 28 canales y estrechos del mundo con tránsitos diarios de IMF PortWatch: media 7 y 30 días, línea base, interanual, índice de disrupción 0-100, capacidad (DWT/día), mezcla por tipo de buque y sparkline de 90 días. Con ?id=<slug> devuelve la serie diaria (~400 días) de un paso.

  {
    "latest": "2026-09-27",
    "source": "IMF PortWatch",
    "chokepoints": [
      { "id": "suez", "avg7": 40, "avg30": 40.7, "baseline": 41,
        "yoy7_pct": -6.4, "vs_baseline_pct": -0.8, "disruption": 1,
        "capacity30": 1536803, "mix30": { "container": 26.6, "tanker": 39.9 },
        "spark90": [47, 34, 44] }
    ]
  }

• GET/v1/imo?chokepoint=hormuz&limit=10

  Avisos oficiales de la Organización Marítima Internacional etiquetados por paso, con severidad (info/watch/action) y resumen propio de CanalIQ en ES/EN. Por los términos de imo.org solo se entrega titular, fecha, tipo y enlace al original. Filtros: ?chokepoint=<slug>&limit=.

  {
    "source": "IMO",
    "notices": [
      { "url": "https://www.imo.org/en/mediacentre/…", "kind": "press",
        "title": "…", "published": "2026-09-30",
        "chokepoints": ["hormuz"], "severidad": "watch",
        "resumen_es": "…", "resumen_en": "…" }
    ]
  }

• GET/v1/security?chokepoint=malacca&days=365

  Incidentes de piratería y robo armado de ReCAAP ISC (cobertura solo Asia) asignados al paso más cercano: conteos a 90 y 365 días y categoría más grave por paso, más la lista de incidentes (fecha, tipo, buque, posición, CAT 1-4). Fuera de Asia la ausencia de datos es «sin cobertura», no «sin incidentes». Filtros: ?chokepoint=<slug>&days=.

  {
    "source": "ReCAAP ISC",
    "coverage": "asia",
    "by_chokepoint": [
      { "chokepoint": "malacca", "n90": 5, "n365": 40,
        "worst_cat": 2, "last_date": "2026-09-17" }
    ],
    "incidents": [
      { "id": "recaap-2026-001", "date": "2026-09-17",
        "incident_type": "Robbery/ Theft", "ship_type": "BULK CARRIER",
        "lat": 1.13, "lon": 103.52, "severity": 3, "chokepoint": "malacca" }
    ]
  }

• GET/v1/chokepoints/conditions?id=suez

  Condiciones en vivo de un paso (Open-Meteo, modelos NOAA/ECMWF): viento y rachas (kn) con dirección, visibilidad, temperatura del aire y del mar, código de tiempo WMO, ola, mar de fondo y periodo, más pronóstico de 3 días con máximos diarios. Fechas en la zona horaria local del paso (campo timezone). No se almacena: caché de 30 min. Dato de modelo, no apto para navegación. Parámetro: ?id=<slug>.

  {
    "id": "suez", "timezone": "Africa/Cairo",
    "source": "Open-Meteo (modelos NOAA/ECMWF)",
    "current": { "wind_kn": 6.6, "wind_dir": 208, "gust_kn": 8.9,
      "visibility_km": 38.5, "temp_c": 25.3, "weather_code": 0,
      "wave_m": 0.44, "wave_dir": 322, "wave_period_s": 4.7,
      "swell_m": 0.44, "sst_c": 26.8 },
    "forecast": [
      { "date": "2026-10-02", "wind_max_kn": 15.8, "gust_max_kn": 22,
        "precip_mm": 0.4, "weather_code": 3, "wave_max_m": 0.5, "swell_max_m": 0.5 }
    ]
  }

• GET/v1/cyclones

  Ciclones tropicales activos de todas las cuencas según GDACS (UE-JRC, ONU-OCHA): nombre, alerta Green/Orange/Red, posición del último boletín, país afectado, intensidad textual, enlace al informe de gdacs.org y pasos del catálogo a ≤800 nm (near_chokepoints con distancia). Complementa /v1/storms (NOAA NHC, Atlántico y Pacífico oriental). Caché de 30 min.

  {
    "source": "GDACS (UE-JRC, ONU-OCHA)", "count": 6,
    "cyclones": [
      { "id": "TC-1001332", "name": "CHOI-WAN-26", "alert": "Green",
        "lat": 16.9, "lon": 145.1, "last_update": "2026-10-01T18:00:00",
        "severity_text": "Tropical Storm (…)",
        "report_url": "https://www.gdacs.org/report.aspx?…",
        "near_chokepoints": [ { "id": "luzon", "nm": 742 } ] }
    ]
  }

• GET/v1/chokepoints/news?id=hormuz&limit=10

  Pulso de noticias por paso: titulares de medios marítimos con severidad (info/watch/action) y puntuación asignadas por IA, y resumen propio de CanalIQ en ES/EN (nunca el texto del medio) con enlace al original. Panamá no se incluye: su pulso es /v1/pulse. Filtros: ?id=<slug>&severidad=&limit=.

  {
    "chokepoint": "hormuz",
    "items": [
      { "url": "https://…", "source": "Lloyd's List", "title": "…",
        "published": "2026-09-30T08:10:00Z", "severidad": "watch", "score": 64,
        "resumen_es": "…", "resumen_en": "…" }
    ]
  }

• POST/v1/ask

  Pregúntale al Canal: respuesta en lenguaje natural (Claude Haiku) SOLO con los datasets de CanalIQ. Body JSON {question (máx. 500 caracteres), lang, chokepoint?}. Con chokepoint=<slug> el contexto incluye la serie de ese paso, sus avisos IMO, ReCAAP, condiciones y noticias, además del resumen mundial. Sin key: 5 preguntas/día por IP (HTTP 429 al agotarse); con key Pro, sin límite.

  curl -X POST https://api.canaliq.koomodo.app/v1/ask \
    -H "Content-Type: application/json" \
    -d '{"question":"¿Cómo está el tráfico en Ormuz?","lang":"es","chokepoint":"hormuz"}'
  
  { "answer": "…", "model": "claude-haiku-4-5",
    "generated": "2026-10-01T23:00:00Z", "disclaimer": "…" }

• GET/v1/queue · /v1/queue/history · /v1/waits

  Agregados derivados de AIS: snapshots de buques en fondeaderos, historia de la cola observada y tiempos de espera. Muestreo cada 15 minutos — no son posiciones crudas.

• GET/v1/status · /v1/lake/normals · /v1/metrics

  Estado del pipeline: frescura de cada dataset (último dato, edad, umbral) y última corrida de cada job de ingesta. Además: normales históricas del Gatún por día del año y métricas diarias por fondeadero.

• GET/health

  Latido del servicio. Útil para monitoreo.

  { "ok": true }

Charts citables del Canal para tu artículo, blog o dashboard: dos formatos que se actualizan solos.

• SVG/v1/embed/queue.svg · /v1/embed/lake.svg

  Una imagen que se redibuja con cada lectura; ideal para artículos, READMEs y newsletters.

  <img src="https://api.canaliq.koomodo.app/v1/embed/queue.svg?theme=light" width="640" alt="Cola del Canal de Panamá — CanalIQ">

• SVG/v1/embed/chokepoint.svg?id=suez

  Tránsitos diarios de cualquiera de los 28 pasos (IMF PortWatch) como SVG embebible. Parámetros: id=<slug> (obligatorio), theme=light|dark, lang=es|en, days=7–400 (90 por defecto). Caché de 15 min.

  <a href="https://canaliq.koomodo.app/mundo/suez"><img src="https://api.canaliq.koomodo.app/v1/embed/chokepoint.svg?id=suez&theme=light&lang=es" width="640" alt="Tránsitos diarios del Canal de Suez — CanalIQ"></a>

• IFRAME/embed/queue · /embed/lake

  La versión compacta del dashboard, en vivo dentro de tu página.

  <iframe src="https://canaliq.koomodo.app/embed/queue?theme=light" width="640" height="360" frameborder="0"></iframe>

Variantes para el lago Gatún: sustituye queue por lake (/v1/embed/lake.svg y /embed/lake). Parámetros: ?theme=light|dark y ?lang= (13 idiomas).

Embeber es gratis; al citar en artículos: «según datos de CanalIQ».

Vista previa en vivo

# Gratuito — cola oficial del Canal
curl https://api.canaliq.koomodo.app/v1/ops

# Gratuito — advisories estructurados
curl "https://api.canaliq.koomodo.app/v1/advisories?limit=10"

# Gratuito — calado máximo vigente
curl https://api.canaliq.koomodo.app/v1/draft

# Pro — historia completa de la cola (CSV con ?format=csv)
curl -H "Authorization: Bearer ciq_xxxxxxxxxxxx" \
  "https://api.canaliq.koomodo.app/v1/pro/ops?days=3650&format=csv"

# Pro — pronóstico de cola a 7 días
curl -H "Authorization: Bearer ciq_xxxxxxxxxxxx" \
  https://api.canaliq.koomodo.app/v1/pro/forecast

Fair use: los datos provienen de fuentes oficiales, verificadas a diario contra los originales, y de muestreo AIS propio; CanalIQ no está afiliado a la Autoridad del Canal de Panamá. Las series se actualizan a ritmo diario o cada 15 minutos según la fuente — cachea las respuestas al menos 15 minutos y enlaza el documento oficial al citar advisories.

¿Dudas técnicas? Escribe a canaliq@koomodo.app.