tr-acikveri

English summary. tr-acikveri is one Python client for Turkish public open-data portals that run CKAN (Istanbul İBB, İzmir, Konya, Gaziantep, Manisa, Trabzon and others): search datasets across many portals, inspect metadata, list resources by format, and download them politely with caching, rate limiting, retries and resume. It reads the CSV files these portals actually publish (Windows-1254 or UTF-8 with BOM, ; delimiters, decimal commas) and GeoJSON, ships a Turkish CLI, and reminds you that every dataset's licence belongs to the publishing portal.

Türkiye'deki açık veri portalları için tek istemci.

Belediyelerin ve kurumların açık veri portallarının çoğu CKAN üzerinde çalışır ve aynı CKAN Action API'sini sunar. tr-acikveri bu portalları tek bir arayüzün arkasına koyar:

• Bir veya birden çok portalda veri seti arama (portallar paralel sorgulanır, hata veren portal aramayı durdurmaz).
• Kurum, etiket, veri seti bilgisi ve biçime göre kaynak listeleme (CSV, GeoJSON, SHP, XLSX, KML ...; portalların tutarsız biçim adları normalleştirilir).
• Kibar indirme: tr-acikveri/<sürüm> User-Agent'ı, sunucu başına hız sınırı, zaman aşımı, Retry-After dikkate alan yeniden deneme, diskte önbellek ve yarıda kalan indirmeyi kaldığı yerden sürdürme (HTTP Range).
• Türkçe dosyalar: cp1254 / UTF-8 BOM kodlama tespiti, ; ayraç tespiti, 1.234,56 gibi sayıların okunması, eski crs alanlı GeoJSON (ör. EPSG:5254).
• İsteğe bağlı pandas / geopandas dönüşümleri ve Türkçe komut satırı (ara, bilgi, indir, portallar, kurumlar, etiketler).

Yalnızca Python standart kütüphanesiyle çalışır; Python 3.9 ve üstü gerekir.

Lisans uyarısı. Bu paket MIT lisanslıdır, ancak indirdiğiniz verilerin lisansı her portala ve veriyi yayımlayan kuruma aittir (İBB Açık Veri Lisansı, İzmir BB Açık Veri Lisansı, CC BY 4.0, CC BY-NC ...). Paket size veriler üzerinde hiçbir hak vermez. Her veri setinin lisansını (bilgi komutu veya Dataset.license_title) okuyun, koşullarına uyun ve kaynak gösterin. Ticari olmayan (NC) lisanslara özellikle dikkat edin.

Kurulum

pip install tr-acikveri               # yalnızca standart kütüphane
pip install "tr-acikveri[pandas]"     # + DataFrame dönüşümü
pip install "tr-acikveri[excel]"      # + XLSX/XLS okuma (pandas + openpyxl)
pip install "tr-acikveri[geo]"        # + GeoDataFrame (geopandas)
pip install "tr-acikveri[certifi]"    # + Mozilla CA paketi (bkz. "TLS sertifikaları")

Hızlı başlangıç (komut satırı)

tr-acikveri portallar                       # CKAN portalları
tr-acikveri portallar --hepsi               # CKAN olmayanlar dahil
tr-acikveri ara otopark -p ibb -p izmir -f csv -n 5
tr-acikveri bilgi ibb ispark-otopark-bilgileri
tr-acikveri indir konya otopark-bilgileri -f csv -o veri/
tr-acikveri kurumlar izmir --json

Örnek çıktı (kısaltılmış, 2026-11-09):

[konya] otopark-bilgileri
    Otopark Bilgileri (CSV) · Destek Hizmetleri Dairesi Başkanlığı
[izmir] otopark-ucretleri
    Otopark Ücretleri (CSV, XLSX) · İZELMAN A.Ş.

Toplam eşleşme 3 (izmir: 2; konya: 1); gösterilen 3.

Ortak seçenekler: --onbellek KLASÖR, --onbellek-suresi SN, --onbelleksiz, --zaman-asimi SN, --aralik SN (aynı sunucuya iki istek arası, varsayılan 1 sn), --yeniden-deneme N, --iletisim E-POSTA (User-Agent'a eklenir), --json. -p portal anahtarı, şehir adı (İzmir, istanbul) veya herhangi bir CKAN adresi olabilir. Yönlendirilen çıktı (ör. > sonuc.json) her zaman UTF-8 yazılır.

Hızlı başlangıç (Python)

from tr_acikveri import AcikVeri

av = AcikVeri(contact="ad.soyad@kurum.edu.tr")      # iletişim adresi önerilir

sonuc = av.search("otopark", portals=["ibb", "izmir", "konya"], formats=["csv"], rows=5)
for ds in sonuc:
    print(ds.portal, ds.name, ds.formats, ds.license_title)
print(sonuc.counts, sonuc.errors)

ds = av.dataset("konya", "otopark-bilgileri")
kaynak = ds.resources_by_format(["csv"])[0]
tablo = av.read_csv(kaynak)                   # indirir (önbellek) ve okur
print(tablo.encoding, tablo.delimiter, tablo.columns)
kapasite = tablo.numeric("bolgekapasite")      # "1.250" -> 1250.0

df = av.to_dataframe(kaynak, numeric=True)     # [pandas]

parklar = av.search("park", portals=["trabzon"], formats=["geojson"]).datasets[0]
geo_kaynak = parklar.resources_by_format(["geojson"])[0]
geo = av.read_geojson(geo_kaynak)              # FeatureCollection dict
gdf = av.to_geodataframe(geo_kaynak)           # [geo]

Tek portal için alt düzey istemci:

from tr_acikveri import CkanClient

ibb = CkanClient("ibb")
sayi, sayfa = ibb.search("bisiklet", formats=["geojson"], sort="metadata_modified desc")
for ds in ibb.iter_search("hava kalitesi", limit=200):
    ...
kayitlar = ibb.datastore_search(resource_id, limit=100, filters={"ilce": "Kadıköy"})

Portal kaydı

Her kayıt 2026-11-09 tarihinde <adres>/api/3/action/status_show adresine yapılan tek bir salt okunur GET isteğiyle doğrulandı; lisans notları portalın license_list ve package_search yanıtlarından alındı. Veri seti sayıları aynı tarihe aittir.

Desteklenmeyen (CKAN API'si yok veya kontrol sırasında erişilemedi) ve portallar --hepsi ile listelenenler: Ankara (seffaf.ankara.bel.tr), Kocaeli (veri.kocaeli.bel.tr), Kayseri, Küçükçekmece, Sağlık Bakanlığı (özel yazılım); Antalya, Sakarya ve ULASAV (ulasav.csb.gov.tr; erişilemedi, API türü doğrulanamadı). Gaziantep, Denizli, Trabzon, Çanakkale, Balıkesir ve Bursa Açık Yeşil portalları ulasav-license kimlikli ortak CKAN şablonunu kullanır; lisans metni her portalın /license sayfasındadır.

Kayıtta olmayan bir CKAN portalı adresle kullanılabilir veya kaydedilebilir:

from tr_acikveri import Portal, register_portal, CkanClient

CkanClient("https://acikveri.ornek.bel.tr").search("imar")
register_portal(Portal("ornek", "Örnek Belediyesi", "https://acikveri.ornek.bel.tr",
                       city="Örnek", license_note="CC BY 4.0"))

Portallar değişir: adres taşınabilir, API kapanabilir. Kayıttaki bilgiler kontrol tarihindeki durumu yansıtır.

API özeti

Yöntem ve kaynaklar

• CKAN Action API v3 — yalnızca okuma eylemleri (status_show, package_search, package_show, resource_show, organization_list, tag_list, license_list, datastore_search), hepsi GET ile. Kaynak: CKAN API belgeleri, https://docs.ckan.org/en/2.9/api/. package_search için rows en fazla 1000'e sınırlanır (CKAN'ın ckan.search.rows_max varsayılanı).
• Biçim filtresi — res_format Solr'da birebir eşleşen bir alan olduğundan, portallarda görülen yazımların tamamı (CSV, csv, .csv, GeoJSON, .shp, Excel ...) sunucuya gönderilir; sonuç ayrıca istemci tarafında normalleştirilmiş biçimle süzülür.
• HTTP — Retry-After (saniye veya HTTP tarihi) ve Range/Content-Range ile sürdürme: RFC 9110 §10.2.3 ve §14. Yeniden deneme 408/425/429/5xx ve ağ hatalarında, üstel bekleme (+%10 rastgele) ile yapılır. Hız sınırı sunucu (host) başınadır ve iş parçacıkları arasında paylaşılır.
• Kodlama — sıra: UTF-8 BOM → UTF-16 BOM → katı UTF-8 → Windows-1254 (cp1254, Türkçe Windows kod sayfası) → ISO-8859-9. Ayraç, ilk 50 satırda en tutarlı sütun sayısını veren adaydır (;, ,, sekme, |; eşitlikte ;).
• Sayılar — parse_number Türkçe yazımı (ondalık virgül, binlik nokta) varsayar; yalnızca nokta içeren ve binlik gruplamaya uymayan değerler (12.5) ondalık okunur. %, TL, ₺ ve boşluklar yok sayılır.
• GeoJSON — RFC 7946 (WGS 84, EPSG:4326). 2008 GeoJSON belirtimindeki crs alanı varsa (urn:ogc:def:crs:EPSG::5254 gibi) geojson_crs bu kodu döndürür ve to_geodataframe onu kullanır.

TLS sertifikaları

Sertifika doğrulaması her zaman açıktır. Bazı portallar (kontrol tarihinde data.ibb.gov.tr) Windows'un yalnızca gerektiğinde indirdiği bir kök sertifikaya zincirlenir; Python bu durumda CERTIFICATE_VERIFY_FAILED hatası verir. certifi kuruluysa (pip install "tr-acikveri[certifi]") paket otomatik olarak Mozilla CA paketini kullanır. Alternatifler: SSL_CERT_FILE ortam değişkeni, HttpClient(ca_file=...) veya HttpClient(ssl_context=...).

Önbellek

Varsayılan klasör TR_ACIKVERI_CACHE ortam değişkeni, yoksa Windows'ta %LOCALAPPDATA%\tr-acikveri, diğer sistemlerde ~/.cache/tr-acikveri'dir. API yanıtları api/ altında (varsayılan 1 gün), indirilen dosyalar files/<portal>/<kaynak kimliği>/ altında tutulur. Her dosyanın yanında kaynak adresi, portal, veri seti, indirme zamanı ve HTTP doğrulayıcılarını içeren bir .meta.json bulunur. İndirilen verileri bir git deposuna eklemeyin.

Sınırlamalar

• Yalnızca CKAN portalları desteklenir; özel yazılımlı portallar (Ankara, Kocaeli, Kayseri, Sağlık Bakanlığı ...) kayıtta yalnızca bilgi amaçlıdır.
• Portal listesi, veri seti sayıları ve lisans notları 2026-11-09 tarihli kontrollere dayanır; değişebilir. Bağlayıcı olan, veri setinin portaldaki lisansıdır.
• Kodlama tespiti sezgiseldir: UTF-8 olarak geçerli olan cp1254 dosyaları (çok nadir) UTF-8 sayılır; gerekirse encoding="cp1254" verin.
• API/HTML türündeki kaynaklar dosya değildir ve varsayılan olarak indirilmez.
• Çok portallı aramada rows portal başına uygulanır; sonuçlar portallar arasında yeniden sıralanmaz.
• Önbellekteki dosya, sunucuda güncellense bile overwrite=True (CLI: --yeniden) verilmedikçe yeniden indirilmez.

Geliştirme

pip install -e ".[dev,pandas]"
pytest --cov=tr_acikveri
ruff check . && ruff format --check src tests && mypy src

Testler gerçek ağa hiç çıkmaz: tests/mockserver.py iki CKAN portalını, hatalı portalları (500, HTML), 429/503 yanıtlarını, bağlantısı yarıda kopan indirmeleri ve Range desteği olmayan sunucuları taklit eden yerel bir HTTP sunucusudur.

Lisans

MIT © 2026 Yusuf Eminoğlu. Bkz. LICENSE. Bu lisans yalnızca yazılımı kapsar; portallardan alınan veriler kendi lisanslarına tabidir.

Academic citation

@software{eminoglu_tr_acikveri,
  author  = {Eminoğlu, Yusuf},
  title   = {tr-acikveri},
  year    = {2026},
  version = {0.1.0},
  url     = {https://github.com/YusufEminoglu/tr_acikveri_sdk}
}

Ayrıca bkz. CITATION.cff.