Açık veri API — dokümantasyon

v2 uçları (önerilen)

Her yanıt { meta, veri } biçimindedir. meta: kaynak, kaynaklar, lisans, veri_tarihi (verinin kendi tarihi), uretim_zamani (sayfalarla aynı derlemede üretilir), sürüm ve belge adresi. Alan adları küçük harf ve alt çizgiyle, birim sonekiyle yazılır (ör. yas_isletme_rezervi_hm3, egilim_cm_yil). Statik dosyalardır; CDN üzerinden sunulur.

Belge: /api/openapi.json (OpenAPI 3.1). Var olmayan statik dosya için Cloudflare'in HTML 404 sayfası döner; hız sınırlı Function uçlarında hatalar { "hata": "…" } JSON gövdesiyle gelir (405, 429, 503).

v1 uçları (korunuyor)

Hızlı başlangıç

# Havzalar (v2): baraj doluluğu ve uydu eğilimi
curl -s https://suharitasi.com/api/v2/havzalar.json | jq '.veri[] | {ad, baraj, uydu}'

# Tek havza: günlük baraj ortalaması
curl -s https://suharitasi.com/api/v2/havza/gediz.json | jq '.veri.baraj_gunluk_ortalama[-3:]'

# OpenAPI 3.1 belgesi
curl -s https://suharitasi.com/api/openapi.json | jq '.paths | keys'

Python

import json, urllib.request

with urllib.request.urlopen("https://suharitasi.com/api/v2/baraj.json") as r:
    d = json.load(r)

print(d["meta"]["veri_tarihi"], d["veri"]["ulusal"]["ortalama_doluluk_yuzde"])
for h in d["veri"]["havzalar"]:
    print(h["havza"], h["ortalama_doluluk_yuzde"], h["degisim_30_gun_puan"])

JavaScript

const r = await fetch("https://suharitasi.com/api/v2/uydu.json");
const { meta, veri } = await r.json();
console.log(meta.tanim);
for (const h of veri.havzalar) console.log(h.havza, h.egilim_cm_yil, h.sinif);

Bilimsel ayrım: ölçüm ve tahmin

/api/v1/havzalar derlenmiş gözlem/künye verisidir./api/v1/kuraklik ise istatistiksel projeksiyondur(tur: "tahmin"): mevsimlik dalgalanma ayıklanır, düz bir eğilim çizgisi çıkarılır ve eğilimin tesadüf olup olmadığı test edilir (teknik adlar: mevsimsel ayrıştırma, OLS trend, Mann-Kendall), tahmin aralıklarıyla. Tahmin uçları, Google Dataset/TechArticle şemasındameasurementTechnique ile işaretlenir ve ölçüm verisiylekarıştırılmaz.

API anahtarı (isteğe bağlı)

• Başlık: Authorization: Bearer sh_… ya da X-Api-Anahtar: sh_…. Sorgu dizesinde anahtar kabul edilmez (günlüklere düşer).
• Anahtarlı istek: 600 istek/dk ve günde 20.000 istek (anahtar başına, /api/v1/havzalar ve /api/v1/kuraklik); yanıtta anahtar (kısa kimlik) ve kalan_kota. Günlük kota aşımında anahtar 24 saat kısıtlanır (429), iptal edilmez.
• Durum: GET /api/anahtar-durum aynı başlıkla bugünkü kullanım, kalan kota ve kısıtı döndürür.
• Akademik ve gazetecilik kullanımı ücretsiz; başvuru [email protected]. Anahtar sunucuda saklanmaz (yalnız SHA-256 özeti); erişim günlüğünde yalnız kısa kimlik ak_… bulunur.
• Koşullar, atıf ve lisans: /api/kosullar/.

Rate-limit ve dayanıklılık

• Sabit pencere sayacı (Cloudflare KV): sayaç anahtarı IP adresinin (IPv6'da /64 önekinin) SHA-256 özetidir; sayaçta ham IP saklanmaz. Erişim günlüğü ayrıdır (30 gün, IP dahil; gizlilik).
• Sınır aşımı: 429; v1 uçlarında Retry-After: 60, MCP'de JSON-RPC hatası. KV erişilemezse fail-open (sınır uygulanmaz).
• Yanıtlar CDN'de kısa süre önbelleklenir (max-age=300); veri günü başına bir kez üretilir.

Durum: veri tazeliği

Her veri kümesinin son veri tarihi ve beklenen güncelleme aralığı (kaynak: /veri/veri-tazelik.json).

Değişiklik günlüğü

• 16.10.2026 · anahtar — İsteğe bağlı API anahtarı: Authorization: Bearer sh_… ile v1 Function uçlarında 600 istek/dk + günlük kota (anonim 60/dk sürer); /api/anahtar-durum ile kota sorgusu; koşullar ve başvuru /api/kosullar/. Günlükte anahtar değil kısa kimlik tutulur.
• 10.10.2026 · v2 — v2 uçları açıldı: tek yazım düzeni (küçük harf + alt çizgi, birim sonekli alan adları), her yanıtta meta bloğu (kaynak, kaynaklar, lisans, veri_tarihi, uretim_zamani, surum, belge). Havza yanıtında baraj (tek tanım), uydu eğilimi ve yayımlı SYGM planları; günlük baraj ve aylık uydu serisi.
• 10.10.2026 · OpenAPI — Tek OpenAPI 3.1 belgesi: /api/openapi.json (eski /api/v1/openapi.json ve /veri/openapi.json aynı içeriği verir). Hata şeması (Hata) ve hız sınırı yanıtları belgelendi.
• 10.10.2026 · v1 — /veri/mevzuat.json ve /veri/sozluk.json yanıtlarına geriye uyumlu alanlar eklendi (resmî başlık, madde özeti, metinde geçen kurum ve süreler; resmî tanım). Mevcut alanlar değişmedi.
• 10.10.2026 · MCP — baraj_sorgu, uydu_sorgu ve tahmin_sorgu araçları eklendi; sunucu kartı parametre şemalarını taşır.

Lisans ve atıf

Su Haritası'nın kendi derlediği tablolar, hesaplamalar ve metinler Creative Commons Atıf 4.0 (CC BY 4.0) ile, kaynak gösterilerek kullanılabilir. Bu lisans üçüncü taraf verisini kapsamaz: DSİ, EPİAŞ, NASA, Resmî Gazete, Mevzuat Bilgi Sistemi, MTA, OpenStreetMap ve diğer kaynakların verisi her kaynağın kendi kullanım koşuluna tabidir. DSİ verisinin ticari amaçla kullanımı DSİ'nin yazılı iznine bağlıdır. Koşullar tablosu: kaynak ve kullanım koşulları. Tahmin çıktıları "Su Haritası tahmini" olarak etiketlenmelidir; ölçüm olarak sunulamaz.