Sviluppatori
API di Hot Air Cappadocia Balloon: stato dei voli, previsioni e tassi di cambio in tempo reale
Un'API JSON in sola lettura per agenti IA, app e partner che hanno bisogno degli stessi dati in tempo reale usati da questo sito: la decisione dell'Aviazione Civile per i settori delle mongolfiere in Cappadocia, le previsioni meteo dell'alba su Göreme e i tassi di cambio con cui mostriamo i prezzi in altre valute.
- URL di base
https://hotaircappadociaballoon.com/api/v1- Formato
- JSON in UTF-8. Date e orari in ISO 8601, in UTC salvo quando il campo indica l'ora locale.
- Autenticazione
- Nessuna. Nessuna chiave API, nessuna registrazione. Tutti gli endpoint sono pubblici e in sola lettura (GET, HEAD, OPTIONS).
- Descrizione leggibile dalle macchine
- openapi.jsonllms.txt
Endpoint
Stato dei voli
GET /api/v1/flight-status
L'autorizzazione al volo del giorno per i tre settori delle mongolfiere in Cappadocia (A, B e C), così come la pubblica SHM Kapadokya, l'ufficio locale dell'Autorità dell'Aviazione Civile, con gli orari di alba e tramonto e una previsione per la prossima alba.
Si aggiorna ogni 30 minuti mentre SHM pubblica i bollettini e resta in cache circa 5 minuti. Risponde 503 con l'errore no_data_yet se non è ancora stato salvato alcun bollettino.
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"
}
}
}Campi principali
sectors.{A,B,C}.status- flyable, not_flyable, pending o unknown.
sectors.{A,B,C}.label- Nome del settore, per esempio Göreme · Uçhisar.
validFor.from / validFor.to- La fascia oraria coperta dal bollettino, in ora locale come la pubblica SHM.
lastUpdatedBySHM- Quando SHM ha aggiornato il bollettino l'ultima volta, in ora locale.
outlook- Cosa significa il bollettino per la prossima alba: morning (today o tomorrow), dateISO e uno stato per settore (cancelled, clear, notYet o pending). state è unavailable quando i dati mancano o sono troppo vecchi.
sunrise / sunset- Orari locali a Göreme.
fetchedAt / checkedAt- Quando è stato scaricato il bollettino e quando è stato controllato SHM l'ultima volta, in UTC.
Previsioni all'alba
GET /api/v1/forecast
Previsioni a 7 giorni per la finestra di decollo all'alba a Göreme, con la probabilità di volo di ogni mattina e i dati meteo che la determinano.
Resta in cache circa 1 ora. La probabilità è la nostra lettura delle previsioni; la decisione vincolante è quella che SHM pubblica nell'endpoint dello stato dei voli.
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
}
]
}Campi principali
dateISO- La mattina, nel formato AAAA-MM-GG.
status- likely, watch o unlikely.
reason- Fattore principale: calm, mixed, highWinds, strongGusts, rain o overcast.
wind_max / wind_gusts- Vento massimo a 80 m e raffica massima a 10 m durante la finestra dell'alba, in km/h.
cloud_cover- Copertura nuvolosa media durante la finestra dell'alba, in %.
precipitation- Precipitazioni totali durante la finestra dell'alba, in mm.
temperature- Temperatura alle 06:00 ora locale, in °C.
weather_code- Codice meteo WMO all'ora della salita.
Tassi di cambio
GET /api/v1/exchange-rate
Tassi di cambio con l'EUR come base, usati per mostrare prezzi indicativi in altre valute.
I browser possono tenerlo in cache circa 5 minuti. Risponde sempre 200: se la fonte dei tassi non è disponibile, restituisce una tabella solo in EUR con degraded impostato a 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
}Campi principali
rates- Codice valuta e tasso rispetto a 1 EUR, per esempio USD e TRY.
available- Valute con un tasso in tempo reale.
rateDate- La data a cui si riferiscono i tassi.
source- TCMB (Banca Centrale della Repubblica di Turchia) o fallback.
degraded- true quando viene restituita la tabella di riserva.
Errori
Gli errori sono JSON con un codice di errore leggibile dalle macchine e un messaggio, e possono includere hint e docs. Un percorso sconosciuto sotto /api risponde 404 not_found. I metodi diversi da GET, HEAD e OPTIONS rispondono 405 method_not_allowed con un'intestazione Allow. Gli errori imprevisti rispondono 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"
}Versioni
I percorsi documentati sono sotto /api/v1 e ogni risposta porta l'intestazione API-Version: 1. Le modifiche incompatibili escono su un nuovo percorso (/api/v2). /api/v1 resta disponibile per almeno 12 mesi dopo l'annuncio di v2. Le dismissioni vengono annunciate con le intestazioni di risposta Deprecation e Sunset e su questa pagina.
Fonti dei dati
- Stato dei voli: bollettini di SHM Kapadokya, l'ufficio dell'Autorità dell'Aviazione Civile in Cappadocia. La previsione spiega un bollettino; non lo sostituisce mai. shmkapadokya.kapadokya.edu.tr
- Previsioni: dati orari di Open-Meteo per l'area di decollo di Göreme.
- Tassi di cambio: tassi giornalieri della Banca Centrale della Repubblica di Turchia (TCMB).
Cosa l'API non fa
Non esiste un'API per prenotazioni, pagamenti o consultazione delle prenotazioni, e quegli endpoint non devono essere usati da terzi. Prezzi e tassi sono indicativi; il prezzo di prenotazione definitivo viene confermato al checkout. Per prenotare un volo, usa il sito.
File leggibili dalle macchine
/openapi.json: Descrizione OpenAPI 3.1 degli endpoint/llms.txt: Riepilogo del sito per agenti IA/.well-known/api-catalog: Catalogo delle API (RFC 9727)
Domande o integrazioni per partner: scrivi a fly@hotaircappadociaballoon.com.