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.
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"
}
}
}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.
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
}
]
}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.
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
}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.
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"
}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
/openapi.json: OpenAPI 3.1 description of the endpoints/llms.txt: Site summary for AI agents/.well-known/api-catalog: API catalog (RFC 9727)
Questions or a partner integration: write to fly@hotaircappadociaballoon.com.