izmir-open-data-py 0.1.0

Izmir Open Data API Client and MCP Server

İzmir Open Data · Python İstemcisi

İzmir Büyükşehir Belediyesi Açık Veri Portalı ve Open API servisleri için modern, asenkron ve tip güvenli (Pydantic) Python istemcisi.

---

🚀 Özellikler

• Tam Asenkron Destek: httpx altyapısı ile non-blocking, yüksek performanslı istekler.
• %100 Tip Güvenliği: API yanıtları Pydantic V2 modellerine dönüştürülür, IDE'lerde otomatik tamamlama (autocompletion) desteği sunar.
• Kapsamlı Kapsama Alanı: ESHOT, İZBAN, Metro, Vapur, BİSİM, İZSU, Otopark, Etkinlikler, Hal Fiyatları ve daha birçok servisi kapsayan ~150 endpoint desteği.
• CLI (Komut Satırı) Aracı: Terminal üzerinden doğrudan açık veriye erişebilme imkanı.
• Model Context Protocol (MCP): AI ajanlarının (Claude, vb.) doğrudan açık veriyi sorgulayabilmesi için hazır bir MCP sunucusu.

📦 Kurulum

Şu anda paket kaynak koddan yüklenebilmektedir (ileride PyPI'a eklenebilir):

# Repoyu klonlayın
git clone https://github.com/AtaCanYmc/izmir-open-data-py.git
cd izmir-open-data-py

# pip ile (tercihen sanal ortamda) kurun
pip install -e .

📖 Temel Kullanım

import asyncio
from izmir_open_data import IzmirClient

async def main():
    async with IzmirClient() as client:
        # BİSİM İstasyonları ve Boş Bisiklet Durumları
        istasyonlar = await client.bisim.get_istasyon_list()
        for ist = istasyonlar.kayitlar[:3]:
            print(f"İstasyon: {ist.adi} | Boş Bisiklet: {ist.bos_bisiklet_sayisi}")

        # Otopark Doluluk Oranları
        otoparklar = await client.otopark.get_list()
        for oto in otoparklar[:3]:
            print(f"Otopark: {oto.name} | Boş Yer: {oto.occupancy.total.free}")

if __name__ == "__main__":
    asyncio.run(main())

Daha detaylı istemci mimarisi ve namespace yapıları için İstemci (Client) Dokümantasyonuna (docs/CLIENT.md) göz atın.

💻 CLI (Komut Satırı) Aracı

Terminal üzerinden herhangi bir script yazmadan İzmir verilerine ulaşabilirsiniz.

# Yardım menüsü
izmir-data --help

# İstediğiniz veri setini çekmek (örn: afet toplanma alanları)
izmir-data get cbs/afetaciltoplanmaalani

🤖 MCP (Model Context Protocol) Sunucusu

Proje entegre bir MCP sunucusuyla gelmektedir. Yapay zeka ajanlarına izmir verilerini öğretmek isterseniz:

# FastMCP sunucusunu başlatın
izmir-mcp dev

Yapay zeka asistanları (Örn. Claude), bu sunucuya bağlandıklarında sistemdeki tüm API'leri kendi başlarına tarayabilir ve sorularınızı gerçek zamanlı verilerle cevaplayabilir.

MCP sunucusunun yetenekleri, LLM araçları ve Claude Desktop entegrasyonu için detaylı MCP Dokümantasyonuna (docs/MCP.md) göz atın.

🧪 Testler ve Geliştirme

Proje kod kalitesini sağlamak için ruff, mypy ve pre-commit kullanmaktadır. Canlı endpoint testleri pytest ile yazılmıştır:

# Canlı veritabanına bağlanıp 150 endpointin anlık durumunu test edin
pytest tests/test_live_endpoints.py -v

📄 Lisans

Bu proje MIT Lisansı ile lisanslanmıştır. Kullanılan veriler İzmir Büyükşehir Belediyesi Açık Veri Portalı ve Açık Kaynak Kodlu API üzerinden sağlanmaktadır.