● Gestito da Tayf Turizm · TÜRSAB n. 2290

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.

Richiesta
curl -s https://hotaircappadociaballoon.com/api/v1/flight-status
Esempio di risposta, abbreviato
{
  "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.

Richiesta
curl -s https://hotaircappadociaballoon.com/api/v1/forecast
Esempio di risposta, abbreviato
{
  "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.

Richiesta
curl -s https://hotaircappadociaballoon.com/api/v1/exchange-rate
Esempio di risposta, abbreviato
{
  "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.

Richiesta
curl -s https://hotaircappadociaballoon.com/api/v1/unknown
Esempio di risposta, abbreviato
{
  "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

Domande o integrazioni per partner: scrivi a fly@hotaircappadociaballoon.com.