● Operated by Tayf Turizm · TÜRSAB #2290

Developers

Hot Air Cappadocia Balloon API: live flight status, forecast and exchange rates

A read-only JSON API for AI agents, apps and partners that need the live data this site runs on: the Civil Aviation flight decision for the Cappadocia balloon sectors, the sunrise weather outlook for Göreme and the exchange rates used to show prices in other currencies.

Base URL
https://hotaircappadociaballoon.com/api/v1
Format
JSON in UTF-8. Timestamps in ISO 8601, UTC unless a field says local time.
Authentication
None. No API key, no sign-up. Every endpoint is public and read-only (GET, HEAD, OPTIONS).
Machine-readable description
openapi.jsonllms.txt

Endpoints

Flight status

GET /api/v1/flight-status

Today's flight authorization for the three Cappadocia balloon sectors (A, B and C) as published by SHM Kapadokya, the local office of the Civil Aviation Authority, with sunrise and sunset times and an outlook for the next sunrise.

Refreshed every 30 minutes while SHM publishes bulletins and cached for about 5 minutes. Answers 503 with error no_data_yet if no bulletin has been stored yet.

Request
curl -s https://hotaircappadociaballoon.com/api/v1/flight-status
Example response, shortened
{
  "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"
    }
  }
}

Main fields

sectors.{A,B,C}.status
flyable, not_flyable, pending or unknown.
sectors.{A,B,C}.label
Sector name, for example Göreme · Uçhisar.
validFor.from / validFor.to
The time window the bulletin covers, local time as SHM publishes it.
lastUpdatedBySHM
When SHM last updated the bulletin, local time.
outlook
What the bulletin means for the next sunrise: morning (today or tomorrow), dateISO and a state per sector (cancelled, clear, notYet or pending). state is unavailable when the data is missing or too old.
sunrise / sunset
Local times in Göreme.
fetchedAt / checkedAt
When the bulletin was fetched and when SHM was last checked, UTC.

Sunrise forecast

GET /api/v1/forecast

A 7-day forecast for the Göreme sunrise launch window, with a flight likelihood for each morning and the weather values behind it.

Cached for about 1 hour. The likelihood is our reading of the forecast; the binding decision is the one SHM publishes in the flight status endpoint.

Request
curl -s https://hotaircappadociaballoon.com/api/v1/forecast
Example response, shortened
{
  "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
    }
  ]
}

Main fields

dateISO
The morning, as YYYY-MM-DD.
status
likely, watch or unlikely.
reason
Main driver: calm, mixed, highWinds, strongGusts, rain or overcast.
wind_max / wind_gusts
Highest wind at 80 m and highest gust at 10 m during the sunrise window, km/h.
cloud_cover
Average cloud cover during the sunrise window, %.
precipitation
Total precipitation during the sunrise window, mm.
temperature
Temperature at 06:00 local time, °C.
weather_code
WMO weather code at climb time.

Exchange rates

GET /api/v1/exchange-rate

Exchange rates with EUR as the base, used to show approximate prices in other currencies.

Browsers may cache it for about 5 minutes. Always answers 200: when the rate source is unavailable it returns an EUR-only table with degraded set to true.

Request
curl -s https://hotaircappadociaballoon.com/api/v1/exchange-rate
Example response, shortened
{
  "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
}

Main fields

rates
Currency code to rate against 1 EUR, for example USD and TRY.
available
Currencies with a live rate.
rateDate
The date the rates apply to.
source
TCMB (Central Bank of the Republic of Türkiye) or fallback.
degraded
true when the fallback table is returned.

Errors

Errors are JSON with a machine-readable error code and a message, and can include hint and docs. An unknown path under /api answers 404 not_found. Methods other than GET, HEAD and OPTIONS answer 405 method_not_allowed with an Allow header. Unexpected failures answer 500.

Request
curl -s https://hotaircappadociaballoon.com/api/v1/unknown
Example response, shortened
{
  "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"
}

Versioning

The documented paths live under /api/v1 and every response carries an API-Version: 1 header. Breaking changes ship under a new path (/api/v2). /api/v1 stays available for at least 12 months after v2 is announced. Deprecations are announced with Deprecation and Sunset response headers and on this page.

Data sources

  • Flight status: bulletins of SHM Kapadokya, the Cappadocia office of the Civil Aviation Authority. The outlook explains a bulletin; it never replaces it. shmkapadokya.kapadokya.edu.tr
  • Forecast: hourly data from Open-Meteo for the Göreme launch area.
  • Exchange rates: daily rates of the Central Bank of the Republic of Türkiye (TCMB).

What the API does not do

There is no booking, payment or reservation API, and those endpoints must not be called by third parties. Prices and rates are informational; the authoritative booking price is confirmed at checkout. To book a flight, use the website.

Machine-readable files

Questions or a partner integration: write to fly@hotaircappadociaballoon.com.