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.
curl -s https://hotaircappadociaballoon.com/api/v1/flight-status{
"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.
curl -s https://hotaircappadociaballoon.com/api/v1/forecast{
"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.
curl -s https://hotaircappadociaballoon.com/api/v1/exchange-rate{
"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.
curl -s https://hotaircappadociaballoon.com/api/v1/unknown{
"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
/openapi.json: Descripción OpenAPI 3.1 de los endpoints/llms.txt: Resumen del sitio para agentes de IA/.well-known/api-catalog: Catálogo de APIs (RFC 9727)
Preguntas o integraciones con socios: escribe a fly@hotaircappadociaballoon.com.