Open data API

v2 endpoints

Each response is { meta, veri } (veri = data). The files are static and served from the CDN; no key is needed and CORS is open (Access-Control-Allow-Origin: *).

Specification: /api/openapi.json (OpenAPI 3.1). Downloadable CSV and GeoJSON files: open data. Translated data pages: Türkiye's water.

Quick start

# Basins: dam fill and satellite trend
curl -s https://suharitasi.com/api/v2/havzalar.json | jq '.veri[] | {ad, baraj, uydu}'

# One basin: daily dam-fill average
curl -s https://suharitasi.com/api/v2/havza/gediz.json | jq '.veri.baraj_gunluk_ortalama[-3:]'

# OpenAPI 3.1
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"])

Field names

Field names are Turkish, lower case, with a unit suffix (_yuzde percent, _km2 km², _km3 km³, _hm3 hm³, _cm_yil cm per year, _puan percentage points). They are the API contract and do not change with the language of this page.

Measurements and projections

/api/v2/tahmin.json is a statistical projection (seasonal decomposition, least-squares trend, Mann-Kendall test, with uncertainty bands). It is not a measurement and must be labelled "Su Haritası projection" when reused. All other endpoints carry compiled observations from official sources.

Rate limits

The static v2 files have no rate limit. The function endpoints (/api/v1/havzalar, /api/v1/kuraklik and the MCP endpoint) allow 60 requests per minute per client, counted separately for each endpoint. Above that the v1 endpoints return 429 with Retry-After: 60; the MCP endpoint returns 429 with a JSON-RPC error. The rate-limit counter keys clients by a hash of IP and user agent. Separately, these endpoints keep a 30-day access log with the IP address, endpoint, status code and time (privacy notice, in Turkish).

Status: data freshness

Latest data date and expected update interval per data source (source:/veri/veri-tazelik.json). The source has published no new dam-fill measurement on weekends so far; the date shown is the latest measurement day.

Changelog and licence

Data changes (additions, method changes, corrections) are logged in /veri/degisiklik-gunlugu.json (entries in Turkish, each linked to a repository commit). Su Haritası's own compilation is CC BY 4.0; third-party data keeps its source's terms (licence and source terms, Turkish). Archived version with a DOI: 10.5281/zenodo.23002677.

The data is informational and is not legal advice.