● Operado por Tayf Turizm · TÜRSAB n.º 2290

Desarrolladores

API de Hot Air Cappadocia Balloon: estado de los vuelos, previsión y tipos de cambio en vivo

Una API JSON de solo lectura para agentes de IA, aplicaciones y socios que necesitan los mismos datos en vivo que usa esta web: la decisión de Aviación Civil para los sectores de globos de Capadocia, la previsión meteorológica del amanecer en Göreme y los tipos de cambio con los que mostramos precios en otras monedas.

URL base
https://hotaircappadociaballoon.com/api/v1
Formato
JSON en UTF-8. Fechas y horas en ISO 8601, en UTC salvo que el campo indique hora local.
Autenticación
Ninguna. Sin clave de API ni registro. Todos los endpoints son públicos y de solo lectura (GET, HEAD, OPTIONS).
Descripción legible por máquinas
openapi.jsonllms.txt

Endpoints

Estado de los vuelos

GET /api/v1/flight-status

La autorización de vuelo del día para los tres sectores de globos de Capadocia (A, B y C), tal como la publica SHM Kapadokya, la oficina local de la Autoridad de Aviación Civil, con las horas de salida y puesta del sol y una previsión para el próximo amanecer.

Se actualiza cada 30 minutos mientras SHM publica boletines y se guarda en caché unos 5 minutos. Responde 503 con el error no_data_yet si todavía no hay ningún boletín guardado.

Petición
curl -s https://hotaircappadociaballoon.com/api/v1/flight-status
Respuesta de ejemplo, abreviada
{
  "fetchedAt": "2026-11-22T06:30:11.396Z",
  "lastUpdatedBySHM": "22.11.2026 - 05:30",
  "validFor": {
    "from": "22.11.2026 05:30",
    "to": "22.11.2026 07:00"
  },
  "sectors": {
    "A": {
      "status": "flyable",
      "label": "Göreme · Uçhisar",
      "message": "Meteorolojik şartların belirlenen saat aralığında uçuş için uygun olduğu değerlendirilmiştir."
    },
    "B": {
      "status": "flyable",
      "label": "Love · Rose Valley"
    },
    "C": {
      "status": "flyable",
      "label": "Ortahisar · Ürgüp"
    }
  },
  "source": {
    "name": "SHM Kapadokya",
    "url": "https://shmkapadokya.kapadokya.edu.tr/",
    "authority": "Republic of Turkey Civil Aviation Authority"
  },
  "sunrise": "07:30",
  "sunset": "17:23",
  "checkedAt": "2026-11-22T09:30:11.735Z",
  "outlook": {
    "state": "ok",
    "morning": "tomorrow",
    "dateISO": "2026-11-23",
    "sectors": {
      "A": "notYet",
      "B": "notYet",
      "C": "notYet"
    }
  }
}

Campos principales

sectors.{A,B,C}.status
flyable, not_flyable, pending o unknown.
sectors.{A,B,C}.label
Nombre del sector, por ejemplo Göreme · Uçhisar.
validFor.from / validFor.to
La franja horaria que cubre el boletín, en hora local tal como la publica SHM.
lastUpdatedBySHM
Cuándo actualizó SHM el boletín por última vez, en hora local.
outlook
Qué significa el boletín para el próximo amanecer: morning (today o tomorrow), dateISO y un estado por sector (cancelled, clear, notYet o pending). state vale unavailable cuando faltan datos o son demasiado antiguos.
sunrise / sunset
Horas locales en Göreme.
fetchedAt / checkedAt
Cuándo se obtuvo el boletín y cuándo se consultó SHM por última vez, en UTC.

Previsión del amanecer

GET /api/v1/forecast

Una previsión de 7 días para la ventana de despegue al amanecer en Göreme, con la probabilidad de vuelo de cada mañana y los datos meteorológicos que la explican.

Se guarda en caché alrededor de 1 hora. La probabilidad es nuestra lectura de la previsión; la decisión vinculante es la que publica SHM en el endpoint de estado de los vuelos.

Petición
curl -s https://hotaircappadociaballoon.com/api/v1/forecast
Respuesta de ejemplo, abreviada
{
  "ok": true,
  "forecast": [
    {
      "day": "Mon",
      "date": "23 Nov",
      "dateISO": "2026-11-23",
      "status": "likely",
      "reason": "calm",
      "temperature": 3,
      "wind_max": 9,
      "wind_gusts": 22,
      "cloud_cover": 85,
      "precipitation": 0,
      "weather_code": 3
    }
  ]
}

Campos principales

dateISO
La mañana, en formato AAAA-MM-DD.
status
likely, watch o unlikely.
reason
Factor principal: calm, mixed, highWinds, strongGusts, rain u overcast.
wind_max / wind_gusts
Viento máximo a 80 m y racha máxima a 10 m durante la ventana del amanecer, en km/h.
cloud_cover
Nubosidad media durante la ventana del amanecer, en %.
precipitation
Precipitación total durante la ventana del amanecer, en mm.
temperature
Temperatura a las 06:00 hora local, en °C.
weather_code
Código meteorológico WMO a la hora del ascenso.

Tipos de cambio

GET /api/v1/exchange-rate

Tipos de cambio con el EUR como base, que usamos para mostrar precios aproximados en otras monedas.

Los navegadores pueden guardarlo unos 5 minutos. Siempre responde 200: si la fuente de los tipos no está disponible, devuelve una tabla solo en EUR con degraded en true.

Petición
curl -s https://hotaircappadociaballoon.com/api/v1/exchange-rate
Respuesta de ejemplo, abreviada
{
  "base": "EUR",
  "rates": {
    "EUR": 1,
    "USD": 1.1176,
    "TRY": 55.9609
  },
  "available": [
    "EUR",
    "USD",
    "TRY"
  ],
  "rateDate": "2026-11-06",
  "fetchedAt": "2026-11-22T09:33:24.995Z",
  "source": "TCMB",
  "degraded": false
}

Campos principales

rates
Código de moneda y su tipo frente a 1 EUR, por ejemplo USD y TRY.
available
Monedas con tipo en vivo.
rateDate
La fecha a la que corresponden los tipos.
source
TCMB (Banco Central de la República de Turquía) o fallback.
degraded
true cuando se devuelve la tabla de respaldo.

Errores

Los errores son JSON con un código de error legible por máquinas y un mensaje, y pueden incluir hint y docs. Una ruta desconocida bajo /api responde 404 not_found. Los métodos distintos de GET, HEAD y OPTIONS responden 405 method_not_allowed con una cabecera Allow. Los fallos inesperados responden 500.

Petición
curl -s https://hotaircappadociaballoon.com/api/v1/unknown
Respuesta de ejemplo, abreviada
{
  "error": "not_found",
  "message": "There is no API endpoint at /api/v1/unknown.",
  "hint": "The public API lives under /api/v1: flight-status, forecast and exchange-rate. Its OpenAPI description is https://hotaircappadociaballoon.com/openapi.json.",
  "docs": "https://hotaircappadociaballoon.com/en/developers"
}

Versiones

Las rutas documentadas están bajo /api/v1 y cada respuesta lleva la cabecera API-Version: 1. Los cambios incompatibles se publican en una ruta nueva (/api/v2). /api/v1 seguirá disponible al menos 12 meses después de anunciar v2. Las retiradas se anuncian con las cabeceras de respuesta Deprecation y Sunset y en esta página.

Fuentes de datos

  • Estado de los vuelos: boletines de SHM Kapadokya, la oficina de la Autoridad de Aviación Civil en Capadocia. La previsión explica un boletín; nunca lo sustituye. shmkapadokya.kapadokya.edu.tr
  • Previsión: datos horarios de Open-Meteo para la zona de despegue de Göreme.
  • Tipos de cambio: tipos diarios del Banco Central de la República de Turquía (TCMB).

Lo que la API no hace

No hay API de reservas, pagos ni consulta de reservas, y esos endpoints no deben usarlos terceros. Los precios y tipos son orientativos; el precio de reserva definitivo se confirma al pagar. Para reservar un vuelo, usa la web.

Archivos legibles por máquinas

Preguntas o integraciones con socios: escribe a fly@hotaircappadociaballoon.com.