Deprem API

Boğaziçi Üniversitesi Kandilli Rasathanesi (KOERI) tarafından yayımlanan son depremleri JSON formatında sunan küçük bir REST API.

Veri kaynağı: KOERI – Son Depremler (Türkiye ve yakın çevresi, son ~500 kayıt).

Telif / kullanım: Sayfada yayımlanan bilgi, veri ve haritalara ilişkin telif hakları Boğaziçi Üniversitesi Rektörlüğü'ne aittir. Kaynak gösterilerek kullanılabilir; ticari kullanım için üniversitenin yazılı izni gerekir.

Gereksinimler

• Node.js 18+ (fetch API yerleşiktir)

Kurulum ve Çalıştırma

npm install
npm start          # üretim
npm run dev        # dosya değişikliklerinde otomatik yeniden başlatma

Varsayılan adres: http://localhost:3000

Uç Noktalar

| Metot | Yol | Açıklama | |---|---|---| | GET | / | API künyesi ve örnekler | | GET | /api/depremler | Filtrelenebilir deprem listesi | | GET | /api/depremler/ozet | Liste özeti, en büyük deprem, büyüklük dağılımı | | GET | /api/saglik | Servis ve kaynak durumu |

Filtre Parametreleri

Tümü isteğe bağlıdır ve birlikte kullanılabilir:

| Parametre | Açıklama | Örnek | |---|---|---| | minMag / maxMag | Büyüklük (ML/Mw/MD) aralığı | minMag=4 | | minDepth / maxDepth | Derinlik (km) aralığı | maxDepth=30 | | minLat / maxLat | Enlem aralığı | minLat=38&maxLat=42 | | minLon / maxLon | Boylam aralığı | minLon=26&maxLon=32 | | q | Yer adında arama (Türkçe karakter duyarsız) | q=marmara, q=muğla → mugla ile eşleşir | | start / end | Tarih aralığı. Sadece YYYY-MM-DD verilirse TR günü kabul edilir | start=2026-09-28&end=2026-09-29 | | limit | Dönecek kayıt sayısı. Verilmezse filtrede eşleşen hepsi döner (en fazla 500) | limit=20 | | offset | Atlanacak kayıt sayısı (sayfalama) | offset=100 | | sort | date | mag | depth (varsayılan date) | sort=mag | | order | asc | desc (varsayılan desc) | order=asc | | fresh=true | Cache'i atlayıp kaynağı yeniden çeker (tek başına kullanılır) | ?fresh=true |

Geçersiz bir parametre verilirse 400 ve Türkçe hata mesajı döner.

Yanıttaki filters nesnesi yalnızca gönderdiğiniz filtreleri içerir; kullanmadığınız parametreler null olarak geri yazılmaz.

Örnekler

# Son 24 saatteki 4 ve üzeri depremler
curl "http://localhost:3000/api/depremler?minMag=4"

# Marmara'da 30 km'den sığ depremler
curl "http://localhost:3000/api/depremler?q=marmara&maxDepth=30"

# Belirli bir tarih aralığı, en büyükten en küçüğe
curl "http://localhost:3000/api/depremler?start=2026-09-28&end=2026-09-29&sort=mag"

# Harita için koordinat kutusu (İstanbul çevresi)
curl "http://localhost:3000/api/depremler?minLat=40.5&maxLat=41.5&minLon=28&maxLon=30"

# Özet
curl "http://localhost:3000/api/depremler/ozet"

Yanıt Formatı

{
  "source": "Boğaziçi Üniversitesi Kandilli Rasathanesi (KOERI)",
  "updated": "2026-09-29T18:20:31.000Z",
  "stale": false,
  "total": 42,
  "count": 20,
  "limit": 20,
  "offset": 0,
  "filters": { "sort": "date", "order": "desc", "minMag": 4 },
  "data": [
    {
      "id": "3a2845e66e5ae995",
      "date": "2026.09.29",
      "time": "20:38:52",
      "datetime": "2026-09-29T17:38:52.000Z",
      "timestamp": 1790703532,
      "latitude": 38.0092,
      "longitude": 37.7045,
      "depthKm": 3.2,
      "magnitude": 2.2,
      "magnitudeType": "ML",
      "ml": 2.2,
      "location": "KUCUKLU-DOGANSEHIR (MALATYA)",
      "region": "MALATYA",
      "solutionType": "İlksel",
      "revised": false
    }
  ]
}

Alan notları:

• Boş değeri olan alanlar hiç dönmez (null yazılmaz). Örneğin kaynakta -.- olan md / mw, parantezsiz yerlerde region, revize edilmemiş satırlarda revisedAt yanıtta görünmez.
• date / time kaynaktaki Türkiye saati (UTC+03:00) değeridir. datetime ISO 8601 (UTC), timestamp ise Unix saniyesi olarak döner.
• magnitude, kaynaktaki ML varsa ML; yoksa Mw, o da yoksa MD'dir. Ham değerler md / ml / mw alanlarında ayrıca durur.
• region, yer adının sondaki (İL) parantezinden çıkarılır ("KUCUKLU-DOGANSEHIR (MALATYA)" → "MALATYA"); parantezsiz yerlerde (ör. "AKDENIZ") alan hiç dönmez.
• solutionType Kandilli'nin çözüm niteliğidir (ör. İlksel, REVIZE01).
• revised satırın revize edildiğini; revisedAt revize damgasını belirtir.

Yapılandırma (ortam değişkenleri)

| Değişken | Varsayılan | Açıklama | |---|---|---| | PORT | 3000 | Dinlenen port | | CACHE_TTL_MS | 60000 | Kaynağın kaç ms'de bir çekileceği | | RETRY_TTL_MS | 20000 | Kaynak hata verirse tekrar deneme aralığı | | KANDILLI_URL | KOERI lst5.asp | Veri kaynağı adresi | | REQUEST_TIMEOUT_MS | 15000 | Kaynağa istek zaman aşımı |

Mimari

src/
  index.js            Sunucu başlatma
  server.js           Express uygulaması, CORS, hata yakalayıcı
  config.js           Ortam değişkenleri
  kandilli/
    client.js         Kaynak isteği + bellek içi cache + stale fallback
    parser.js         KOERI sabit genişlikli tablosunun ayrıştırılması
  routes/
    depremler.js      /api/depremler uçları
  lib/
    filters.js        Filtreleme, sıralama, sayfalama, Türkçe normalize
    errors.js         HttpError yardımcıları

• Kaynak sayfa her istekte çekilmez; CACHE_TTL_MS boyunca cache'den cevap verilir.
• Kaynak erişilemezse en son başarılı veri stale: true işaretiyle döndürülür.
• Kaynak HTML'i windows-1254 (Türkçe) kodlamasıyla çözümlenir.