izmir-open-data-js 🌊

İzmir Büyükşehir Belediyesi Açık Veri Portalı (acikveri.bizizmir.com) API'lerini JavaScript ve TypeScript projelerinizde kolayca kullanmanızı sağlayan hafif ve modern bir kütüphanedir.

✨ Özellikler

• 🚀 Hızlı Başlangıç: Karmaşık API uç noktalarıyla uğraşmadan veriye ulaşın.
• 📊 Geniş Veri Yelpazesi: Eczanelerden ulaşım ağlarına kadar birçok veriye erişim.
• 🔄 Modern Yapı: async/await desteği ile temiz ve okunabilir kod.
• 🏗️ Esnek: Hem Node.js hem de modern tarayıcı ortamlarında kullanılabilir.
• 📦 CKAN Desteği: Açık veri portalının CKAN API'si üzerinden detaylı veri setlerine erişim.
• 🤖 MCP Sunucusu: LLM'lerin (Örn: Claude Desktop) kullanabilmesi için gömülü Model Context Protocol modülü (izmir-mcp).
• 💻 CLI Aracı: Terminal üzerinden komut satırı aracılığıyla verilere anında ulaşıp tablo çizebilme (izmir-cli).
• 💡 TypeScript: %100 Typescript desteği, Generic typelar ile güvenli veri yapıları.

🚀 Kurulum

Projeye dahil etmek için npm veya yarn kullanabilirsiniz:

npm install izmir-open-data-js
# veya
yarn add izmir-open-data-js

🛠️ Kullanım

Kütüphaneyi projenize dahil ettikten sonra async/await yapısını kullanarak verilere hızlıca erişebilirsiniz.

Örnek: Nöbetçi Eczaneleri Listeleme

import { IzmirAPI } from 'izmir-open-data-js';

const api = new IzmirAPI();

async function verileriGetir() {
  try {
    // Güncel nöbetçi eczane listesini çeker
    const eczaneler = await api.eczaneler.getNobetciList();
    console.log("Nöbetçi Eczaneler:", eczaneler);
  } catch (err) {
    console.error("Veri çekme hatası:", err.message);
  }
}

verileriGetir();

Örnek: ESHOT Hat ve Durak Bilgileri

import { IzmirAPI } from 'izmir-open-data-js';

const api = new IzmirAPI();

async function eshotVerileri() {
  // Tüm ESHOT hatlarını çek (~441 hat)
  const hatlar = await api.eshot.getHatlar();
  console.log(`Toplam ${hatlar.length} hat bulundu`);
  
  // İlk 10 hattı göster
  hatlar.slice(0, 10).forEach(hat => {
    console.log(`Hat ${hat.HAT_NO}: ${hat.HAT_ADI}`);
  });

  // Tüm durakları çek (~11,770 durak)
  const duraklar = await api.eshot.getDuraklar();
  console.log(`Toplam ${duraklar.length} durak mevcut`);

  // Metro, İzban, Vapur bağlantılı hatları çek
  const baglantilar = await api.eshot.getBaglantiHatlari();
  const metroHatlari = baglantilar.filter(h => h.BAGLANTI_TIP_ID === 1);
  console.log(`Metro bağlantılı ${metroHatlari.length} hat var`);
}

eshotVerileri();

💻 CLI Aracı Kullanımı

Projeyi global olarak yüklediyseniz (veya npx üzerinden) verileri harika terminal tablolarıyla hızlıca çekebilirsiniz.

# ESHOT hatlarını ve duraklarını komut satırından görüntüleyin
npx izmir-cli get cbs/hastaneler

# Nöbetçi Eczaneleri hızlıca listeleyin
npx izmir-cli get nobetcieczaneler

Daha fazla detay için: CLI Dokümantasyonu

🤖 MCP (Model Context Protocol) Entegrasyonu

Claude Desktop gibi LLM ajanlarınızın İzmir verilerini yerel olarak keşfedip sorgulayabilmesi için sisteme gömülü bir MCP Sunucusu eklenmiştir. Claude konfigürasyonunuza şu satırları ekleyerek paketi bir yapay zeka aracı olarak kullanabilirsiniz:

"mcpServers": {
  "izmir-open-data": {
    "command": "npx",
    "args": ["-y", "izmir-open-data-js"]
  }
}

Daha fazla detay için: MCP Dokümantasyonu

📋 Tüm Endpoint'ler

🏥 Eczaneler (api.eczaneler)

| Metot | Açıklama | | :--- | :--- | | getNobetciList() | Nöbetçi eczanelerin listesini döner | | getList() | Tüm eczanelerin listesini döner |

👨‍⚕️ Sağlık (api.saglik)

| Metot | Açıklama | | :--- | :--- | | getAcilYardimIstasyonlariList() | Acil yardım istasyonlarını listeler | | getAileSagligiMerkezleriList() | Aile sağlığı merkezlerini listeler | | getAgizDisSagligiMerkezleriList() | Ağız ve diş sağlığı merkezlerini listeler | | getAnaCocukSagligiMerkezleriList() | Ana çocuk sağlığı merkezlerini listeler | | getDalMerkezleriList() | Dal merkezlerini listeler | | getHastanelerList() | Hastaneleri listeler | | getKanMerkezleriList() | Kan merkezlerini listeler | | getLaboratuvarlarList() | Laboratuvarları listeler | | getPolikliniklerList() | Poliklinikleri listeler | | getTipMerkezleriList() | Tıp merkezlerini listeler | | getToplumSagligiMerkezleriList() | Toplum sağlığı merkezlerini listeler | | getVeremSavasDispanserleriList() | Verem savaş dispanserlerini listeler | | getVeterinerliklerList() | Veterinerlikleri listeler |

💧 İZSU (api.izsu)

| Metot | Açıklama | | :--- | :--- | | getSuUretimiDagilimi() | Su üretiminin aylara ve kaynaklara göre dağılımını döner | | getGunlukSuUretimi() | Günlük su üretimi miktarlarını döner | | getBarajDolulukOranlari() | Barajların doluluk oranlarını döner | | getHaftalikSuAnalizi() | Haftalık su analiz sonuçlarını döner | | getBarajSuKaliteRaporlari() | Baraj su kalite raporlarını döner | | getArizaKaynakliKesintiList() | Arıza kaynaklı su kesintilerini listeler | | getBarajVeKuyuList() | Baraj ve kuyuları listeler | | getIzsuSubeList() | İZSU şubelerini listeler | | getIzsuVezneList() | İZSU veznelerini listeler |

🚌 Ulaşım - ESHOT (api.eshot)

| Metot | Açıklama | | :--- | :--- | | getYakinDurakList(enlem, boylam) | Belirtilen konuma yakın ESHOT duraklarını listeler | | getDuragaYaklasanOtobusList(durakId) | Bir durağa yaklaşan otobüsleri listeler | | getHattinYaklasanOtobusleri(hatId, durakId) | Bir hattın durağa yaklaşan otobüslerini listeler | | getHatOtobusKonumlari(hatId) | Hatta ait otobüslerin anlık konum bilgilerini döner | | getHatlar() | Tüm ESHOT hat bilgilerini döner (~441 hat) | | getHareketSaatleri() | Tüm otobüs hareket saatlerini döner (~101,000+ kayıt) | | getDuraklar() | Tüm ESHOT duraklarını listeler (~11,770 durak) | | getHatGuzergahlari() | Hat güzergah koordinatlarını döner (~563,000+ nokta) | | getBaglantiTipleri() | Diğer ulaşım araçları ile bağlantı tiplerini döner | | getBaglantiHatlari() | Diğer ulaşım araçlarına bağlantılı hatları ve çalışma saatlerini döner (~583 kayıt) |

🚲 Ulaşım - BİSİM (api.bisim)

| Metot | Açıklama | | :--- | :--- | | getIstasyonList() | BİSİM istasyonlarını listeler |

🚃 Ulaşım - Tramvay (api.tramvay)

| Metot | Açıklama | | :--- | :--- | | getHatList() | Tramvay hatlarını listeler | | getSeferList() | Tüm tramvay sefer bilgilerini listeler | | getIstasyonList(seferId) | Sefer numarasına göre tramvay istasyonlarını listeler | | getSeferSiklikList(seferId) | Sefer numarasına göre sefer sıklıklarını döner | | getPlanlananiSeferSayilari() | Metro ve tramvay için aylık planlanan sefer sayılarını döner (~74 kayıt) | | getDurakMesafeleri(hat) | Tramvay hattı durak mesafelerini döner. Hat: 'karsiyaka', 'konak-sag', 'konak-sol', 'cigili' |

🚇 Ulaşım - Metro (api.metro)

| Metot | Açıklama | | :--- | :--- | | getIstasyonList() | Metro istasyonlarını listeler | | getDurakMesafeleri() | Metro istasyonları arasındaki mesafe bilgilerini döner |

🚆 Ulaşım - İZBAN (api.izban)

| Metot | Açıklama | | :--- | :--- | | getTarife(binisId, inisId, aktarma, httMi) | İZBAN fiyat tarifesini hesaplar | | getIstasyonList() | İZBAN istasyonlarını listeler | | getHareketSaatleri(kalkisId, varisId) | İZBAN hareket saatlerini döner | | getDurakMesafeleri() | İZBAN istasyonları arasındaki mesafe bilgilerini döner |

⛴️ Ulaşım - Vapur (api.vapur)

| Metot | Açıklama | | :--- | :--- | | getHareketSaatleri(kalkis, varis, gunTipi, detay) | Vapur hareket saatlerini döner | | getCalismaGunleri() | Vapurların çalışma günlerini döner | | getHareketSaatleriByHat(iskeleId, gunId) | İskele bazlı hareket saatlerini döner | | getIskeleList() | Vapur iskelelerini listeler | | getDetayList() | Vapurların kapasite ve donanım bilgilerini döner (~20 gemi) |

🚃 Ulaşım - Tren & Diğer (api.tren)

| Metot | Açıklama | | :--- | :--- | | getTrenGarlariList() | Tren garlarını listeler | | getHavaalaniList() | Havaalanlarını listeler | | getOtobusTerminalleriList() | Şehirlerarası otobüs terminallerini listeler | | getAracMuayeneIstasyonlariList() | Araç muayene istasyonlarını listeler |

🅿️ Otopark (api.otopark)

| Metot | Açıklama | | :--- | :--- | | getList() | Otoparkların doluluk ve konum bilgilerini döner | | getUcretler(limit, offset) | İzelman otopark ücretlerini döner (CKAN) |

💳 İzmirimKart (api.izmirimkart)

| Metot | Açıklama | | :--- | :--- | | getDolumNoktalari() | İzmirimKart dolum noktalarının adres ve konum bilgilerini döner |

🚦 Trafik (api.trafik)

| Metot | Açıklama | | :--- | :--- | | getKameraList() | Trafik kameralarının konum bilgilerini döner (~92 kamera) |

🚕 Taksi (api.taksi)

| Metot | Açıklama | | :--- | :--- | | getDurakList() | Taksi duraklarını listeler |

🎭 Etkinlikler (api.etkinlikler)

| Metot | Açıklama | | :--- | :--- | | getList() | Kültür sanat etkinliklerini listeler | | getEtkinlikById(id) | Belirli bir etkinliğin detaylarını döner |

🌡️ İklim (api.iklim)

| Metot | Açıklama | | :--- | :--- | | getGunlukHavaKalitesiOlcumleri(tarih) | Belirtilen tarihe göre hava kalitesi ölçümlerini döner | | getHavaKalitesiIstasyonlari() | Hava kalitesi ölçüm istasyonlarının konum bilgilerini döner |

🛒 Pazarlar (api.pazarlar)

| Metot | Açıklama | | :--- | :--- | | getList() | Semt pazar yerlerini listeler | | getBalikHalFiyatlari(tarih) | Balık hal fiyatlarını döner | | getSebzeMeyveHalFiyatlari(tarih) | Sebze meyve hal fiyatlarını döner |

🏛️ Muhtarlıklar (api.muhtarliklar)

| Metot | Açıklama | | :--- | :--- | | getList() | Muhtarlıkları listeler |

📶 WiFi (api.wizmirnet)

| Metot | Açıklama | | :--- | :--- | | getList() | Ücretsiz kablosuz internet noktalarını listeler |

⚠️ Afetler (api.afetler)

| Metot | Açıklama | | :--- | :--- | | getAcilDurumToplanmaAlanlari() | Afet ve acil durum toplanma alanlarını listeler |

🏢 Hizmet Noktaları (api.hizmet)

| Metot | Açıklama | | :--- | :--- | | getHizmetNoktaList() | İzBB hizmet noktalarını listeler |

📚 Eğitim (api.egitim)

| Metot | Açıklama | | :--- | :--- | | getEngelliOkullariList() | Engelliler okullarını listeler | | getAnaokullarList() | Anaokullarını listeler | | getEtutMerkezleriList() | Etüt merkezlerini listeler | | getHalkEgitimList() | Halk eğitim merkezlerini listeler | | getIlkokullarList() | İlkokulları listeler | | getKolejlerList() | Kolejleri listeler | | getLiselerList() | Liseleri listeler | | getMeslekLiseleriList() | Meslek liselerini listeler | | getOrtaokullarList() | Ortaokulları listeler | | getSanatOkullariList() | Sanat okullarını listeler | | getUniversitelerList() | Üniversiteleri listeler | | getMilliEgitimList() | Milli eğitim müdürlüklerini listeler |

📖 Kütüphane & Kültür (api.kutuphane)

| Metot | Açıklama | | :--- | :--- | | getKutuphanelerList() | Kütüphaneleri listeler | | getKulturMerkezleriList() | Kültür merkezlerini listeler | | getOperaVeBaleList() | Opera ve bale mekanlarını listeler | | getGaleriVeSalonlarList() | Sanat galerisi ve sergi salonlarını listeler | | getSenfoniOrkestrasiList() | Senfoni orkestrası mekanlarını listeler | | getSinemalarList() | Sinemaları listeler | | getTiyatrolarList() | Tiyatroları listeler | | getMuzelerList() | Müzeleri listeler |

🏛️ Tarihi Yerler (api.tarihi)

| Metot | Açıklama | | :--- | :--- | | getAntikKentlerList() | Antik kentleri listeler | | getAntikKentYapilariList() | Antik kent yapılarını listeler | | getKoskVeKonaklarList() | Köşk ve konakları listeler | | getKuleAnitHeykellerList() | Kule, anıt ve heykelleri listeler | | getTarihiCarsiHanlarList() | Tarihi çarşı ve hanları listeler | | getTarihiSuYapilariList() | Tarihi su yapılarını listeler | | getTarihiYapilarList() | Tarihi yapıları listeler |

🏖️ Plaj & Turizm (api.plaj)

| Metot | Açıklama | | :--- | :--- | | getPlajlarList() | Plajları listeler | | getHamamlarList() | Hamamları listeler | | getKaplicalarList() | Kaplıcaları listeler | | getFuarList() | Fuar alanlarını listeler |

🏛️ Kamu Kurumları (api.kamu)

| Metot | Açıklama | | :--- | :--- | | getBankalarList() | Bankaları listeler | | getBelediyelerList() | Belediye ve birimleri listeler | | getBolgeMudurlukleriList() | Bölge müdürlüklerini listeler | | getDefterdarliklarList() | Defterdarlıkları listeler | | getDerneklerList() | Dernekleri listeler | | getEvlendirmeDaireleriList() | Evlendirme dairelerini listeler | | getIlIlceMudurlukleriList() | İl ve ilçe müdürlüklerini listeler | | getItfaiyeGruplariList() | İtfaiye gruplarını listeler | | getKonsolosluklarList() | Konsoloslukları listeler | | getMeslekOdalariList() | Meslek odalarını listeler | | getNoterlerList() | Noterleri listeler | | getNufusMudurlukleriList() | Nüfus müdürlüklerini listeler | | getPttList() | PTT şubelerini listeler | | getTurizmDanismaList() | Turizm danışma merkezlerini listeler | | getVergiDaireleriList() | Vergi dairelerini listeler | | getMaskematikNoktalariList() | Maskematik istasyonlarını listeler |

👨‍👩‍👧‍👦 Sosyal Hizmetler (api.sosyal)

| Metot | Açıklama | | :--- | :--- | | getAileDayanismaMerkezleriList() | Aile dayanışma merkezlerini listeler | | getCocukGenclikMerkezleriList() | Çocuk ve gençlik merkezlerini listeler | | getCocukYuvalariList() | Çocuk yuvalarını listeler | | getHuzurevleriList() | Huzurevlerini listeler | | getToplumMerkezleriList() | Toplum merkezlerini listeler | | getYetistirmeYurtlariList() | Yetiştirme yurtlarını listeler |

⚽ Spor (api.spor) (Deneysel)

| Metot | Açıklama | | :--- | :--- | | getHipodromList() | Hipodromları listeler | | getSporSalonlariList() | Spor salonlarını listeler | | getStadyumlarList() | Stadyumları listeler | | getYuruyusYollari() | Yürüyüş ve bisiklet parkurlarını döner (mesafe, zorluk, süre bilgileri) |

⚠️ Not: Bazı spor endpoint'leri API'de henüz tam aktif olmayabilir.

🗺️ Coğrafi Özellikler (api.cografi)

| Metot | Açıklama | | :--- | :--- | | getAdaYarimadaList() | Ada ve yarımadaları listeler | | getBurunlarList() | Burunları listeler | | getDagTepeList() | Dağ ve tepeleri listeler | | getGollerList() | Gölleri listeler | | getKorfezKoylarList() | Körfez ve koyları listeler | | getNehirCaylarList() | Nehir ve çayları listeler | | getOrmanlarList() | Ormanları listeler | | getMeydanlarList() | Meydanları listeler |

🎫 İztek - İzmirim Kart (api.iztek)

| Metot | Açıklama | | :--- | :--- | | getAskidaIzmirimKartIstatistik() | Askıda İzmirim Kart istatistiklerini döner |

📖 API Kaynağı

Bu kütüphane, verileri İzmir Büyükşehir Belediyesi Açık Veri Portalı üzerinden çekmektedir. Veri yapılarındaki herhangi bir değişiklik veya kesinti portal kaynaklı olabilir.

🤝 Katkıda Bulunma

İzmir için geliştirilen bu projeye katkı sağlamak harika olur! Yeni bir özellik eklemek veya bir hatayı düzeltmek için:

1. Bu depoyu (repository) fork edin.
2. Yeni bir dal (branch) oluşturun: git checkout -b feature/yeniOzellik
3. Değişikliklerinizi yapın ve commit edin: git commit -m 'Ekle: Yeni API uç noktası'
4. Dalınızı push edin: git push origin feature/yeniOzellik
5. Bir Pull Request açın.

🧪 Test

# Unit testleri çalıştır
npm test

# Watch modunda testler
npm run test:watch

# Coverage raporuyla testler
npm run test:coverage

# Canlı API testleri (opsiyonel)
npm run test:live

📄 Lisans

Bu proje Apache 2.0 Lisansı ile lisanslanmıştır.

[!NOTE]
Bu paket, geliştiricilerin İzmir'in açık verilerini projelerine daha hızlı entegre etmesi için hazırlanmış bir topluluk projesidir. Resmi kurumlarla doğrudan bir bağı yoktur.