motion-depremapi 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 motion-depremapi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# 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](http://www.koeri.boun.edu.tr/scripts/lst5.asp) (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
+
+```bash
+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
+
+```bash
+# 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ı
+
+```json
+{
+  "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.

package/bin/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * motion-depremapi CLI giriş noktası.
+ *
+ *   motion-depremapi                 # 3000 portunda başlat
+ *   motion-depremapi --port 8080     # farklı port
+ *   motion-depremapi --help          # kullanım
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pkg = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"),
+);
+
+const argv = process.argv.slice(2);
+
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(`${pkg.name} v${pkg.version}
+${pkg.description}
+
+Kullanım:
+  ${pkg.name} [seçenekler]
+
+Seçenekler:
+  --port <n>    Dinlenecek port (varsayılan: PORT ortam değişkeni veya 3000)
+  -v, --version Sürümü yazdır
+  -h, --help    Bu yardımı yazdır
+
+Ortam değişkenleri:
+  PORT           Dinlenecek port
+  CACHE_TTL_MS   Kaynağın kaç ms'de bir çekileceği (varsayılan 60000)
+  KANDILLI_URL   Veri kaynağı adresi
+
+Örnekler:
+  ${pkg.name}
+  ${pkg.name} --port 8080
+  curl "http://localhost:3000/api/depremler?minMag=4"
+
+Veri kaynağı: Boğaziçi Üniversitesi Kandilli Rasathanesi (KOERI).
+Ticari kullanım için Boğaziçi Üniversitesi Rektörlüğü'nden izin gerekir.`);
+  process.exit(0);
+}
+
+if (argv.includes("--version") || argv.includes("-v")) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+await import("../src/index.js");

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "motion-depremapi",
+  "version": "1.0.0",
+  "description": "Kandilli Rasathanesi (KOERI) son depremlerini filtreleyerek JSON sunan hazır REST API",
+  "type": "module",
+  "main": "src/server.js",
+  "exports": {
+    ".": "./src/server.js"
+  },
+  "bin": {
+    "motion-depremapi": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "prepublishOnly": "node bin/cli.js --version"
+  },
+  "keywords": [
+    "deprem",
+    "earthquake",
+    "earthquakes",
+    "kandilli",
+    "koeri",
+    "bogazici",
+    "turkey",
+    "rest-api",
+    "express",
+    "seismic"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "express": "^5.1.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,39 @@
+/**
+ * Uygulama yapılandırması.
+ * Öncelik: komut satırı argümanı > ortam değişkeni > varsayılan.
+ */
+
+/** `--anahtar değer` veya `--anahtar=value` biçimini okur. */
+function readArg(name) {
+  const argv = process.argv.slice(2);
+  const index = argv.indexOf(`--${name}`);
+  if (index !== -1 && argv[index + 1] && !argv[index + 1].startsWith("--")) {
+    return argv[index + 1];
+  }
+  const inline = argv.find((a) => a.startsWith(`--${name}=`));
+  if (inline) return inline.slice(name.length + 3);
+  return null;
+}
+
+/** Komut satırı bayrağı > ortam değişkeni > varsayılan sırasıyla okur. */
+const read = (flag, envName, fallback) =>
+  readArg(flag) ?? process.env[envName] ?? fallback;
+
+export const config = {
+  /** API'nin dinleyeceği port */
+  port: Number(read("port", "PORT", 3000)),
+
+  /** Kandilli sayfasının en fazla kaç ms'de bir çekileceği (cache süresi) */
+  cacheTtlMs: Number(read("cache-ttl-ms", "CACHE_TTL_MS", 60_000)),
+
+  /** Cache dolduktan sonra tekrar deneme aralığı */
+  retryTtlMs: Number(process.env.RETRY_TTL_MS || 20_000),
+
+  /** Kaynak sayfa adresi (KOERI "son depremler" listesi) */
+  sourceUrl:
+    process.env.KANDILLI_URL ||
+    "http://www.koeri.boun.edu.tr/scripts/lst5.asp",
+
+  /** Kaynağa yapılacak isteğin zaman aşımı */
+  requestTimeoutMs: Number(process.env.REQUEST_TIMEOUT_MS || 15_000),
+};

package/src/index.js

@@ -0,0 +1,26 @@
+import { createApp } from "./server.js";
+import { config } from "./config.js";
+import { getEvents } from "./kandilli/client.js";
+
+const app = createApp();
+
+const server = app.listen(config.port, () => {
+  console.log(`✔ Deprem API çalışıyor: http://localhost:${config.port}`);
+  console.log(`  Örnek: http://localhost:${config.port}/api/depremler?minMag=3&limit=10`);
+
+  // İlk veriyi arka planda çek ki ilk istek beklemesin.
+  getEvents()
+    .then((s) =>
+      console.log(`  Kaynak yüklendi: ${s.events.length} kayıt (KOERI)`),
+    )
+    .catch((err) => console.warn(`  Kaynak ilk denemede alınamadı: ${err.message}`));
+});
+
+function shutdown(signal) {
+  console.log(`\n${signal} alındı, kapatılıyor...`);
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 3000).unref();
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));

package/src/kandilli/client.js

@@ -0,0 +1,92 @@
+/**
+ * Kandilli Rasathanesi kaynağından veri çeken ve sonucu bellekte cache'leyen istemci.
+ *
+ * KOERI'ye her istekte tekrar gitmemek için TTL tabanlı bir cache kullanılır.
+ * Kaynak geçici olarak erişilemezse en son başarılı veri "stale" olarak döndürülür.
+ */
+
+import { config } from "../config.js";
+import { parseKandilliPage } from "./parser.js";
+import { HttpError } from "../lib/errors.js";
+
+const state = {
+  events: [],
+  fetchedAt: null,
+  expiresAt: 0,
+  error: null,
+  sourceUrl: config.sourceUrl,
+};
+
+/** Kaynak sayfayı indirir ve metne çevirir (windows-1254). */
+async function fetchSource() {
+  const response = await fetch(config.sourceUrl, {
+    headers: {
+      "User-Agent":
+        "deprem-api/1.0 (Kandilli Rasathanesi verisi; kisisel/egitim amacli)",
+      Accept: "text/html,application/xhtml+xml",
+    },
+    signal: AbortSignal.timeout(config.requestTimeoutMs),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Kaynak HTTP ${response.status} döndürdü`);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  // KOERI sayfası windows-1254 kodlamalıdır; desteklenmiyorsa latin1'e düşülür.
+  try {
+    return new TextDecoder("windows-1254").decode(buffer);
+  } catch {
+    return new TextDecoder("latin1").decode(buffer);
+  }
+}
+
+function snapshot() {
+  return {
+    events: state.events,
+    fetchedAt: state.fetchedAt,
+    expiresAt: state.expiresAt,
+    stale: state.error !== null,
+    error: state.error,
+    sourceUrl: state.sourceUrl,
+  };
+}
+
+/**
+ * Güncel deprem listesini döndürür.
+ * @param {{ force?: boolean }} [options] force=true ile cache'i yok sayar.
+ */
+export async function getEvents({ force = false } = {}) {
+  const now = Date.now();
+
+  if (!force && state.fetchedAt && now < state.expiresAt) {
+    return snapshot();
+  }
+
+  try {
+    const html = await fetchSource();
+    const events = parseKandilliPage(html);
+
+    if (events.length === 0) {
+      throw new Error("Kaynak sayfadan hiç deprem kaydı çözümlenemedi");
+    }
+
+    state.events = events;
+    state.fetchedAt = new Date().toISOString();
+    state.expiresAt = now + config.cacheTtlMs;
+    state.error = null;
+  } catch (error) {
+    // Kaynak geçici olarak yoksa eldeki veriyi koru, kısa süre sonra tekrar dene.
+    state.error = error.message;
+    state.expiresAt = now + config.retryTtlMs;
+    // Hiç kayıt yoksa (ilk istekte kaynak yoksa) 503 döndür.
+    if (state.events.length === 0) {
+      throw new HttpError(
+        503,
+        `Kandilli kaynağına şu anda ulaşılamıyor: ${error.message}`,
+      );
+    }
+  }
+
+  return snapshot();
+}

package/src/kandilli/parser.js

@@ -0,0 +1,124 @@
+/**
+ * KOERI (Kandilli Rasathanesi) "Son Depremler" sayfasının ayrıştırılması.
+ *
+ * Sayfa içindeki <pre> bloğunda sabit genişlikli bir tablo bulunur:
+ *
+ *   Tarih      Saat      Enlem(N)  Boylam(E) Derinlik(km)  MD   ML   Mw    Yer                          Çözüm Niteliği
+ *   ---------- --------  --------  -------   ----------    ------------    --------------                --------------
+ *   2026.09.29 20:38:52  38.0092   37.7045        3.2      -.-  2.2  -.-   KUCUKLU-DOGANSEHIR (MALATYA)  İlksel
+ *
+ * Kaynak sayfa windows-1254 (Türkçe) kodlamalıdır; çözümleme istemci tarafında yapılır.
+ */
+
+import { createHash } from "node:crypto";
+
+/** Satırın bir veri satırı olup olmadığını anlayan başlangıç kalıbı. */
+const ROW_START = /^(\d{4}\.\d{2}\.\d{2})\s+(\d{2}:\d{2}:\d{2})\s+(.*)$/;
+
+/** Enlem, boylam, derinlik ve üç büyüklük değerini sırayla yakalar. */
+const NUMBERS =
+  /^\s*(-?\d+(?:\.\d+)?|-\.-)\s+(-?\d+(?:\.\d+)?|-\.-)\s+(-?\d+(?:\.\d+)?|-\.-)\s+(\S+)\s+(\S+)\s+(\S+)\s+(.+)$/;
+
+/** "-.-" gibi eksik değerleri null'a çevirir. */
+const toNumber = (value) => {
+  if (!value || value === "-.-" || value === "..." || value === "-") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+/** Yer adının sondaki "(İL)" parantezinden bölge/il bilgisini çıkarır. */
+const extractRegion = (location) => {
+  const match = /\(([^()]+)\)\s*$/.exec(location);
+  return match ? match[1].trim() : null;
+};
+
+/**
+ * Değeri olmayan (null/undefined) alanları çıktıdan çıkarır.
+ * Kaynakta "-.-" görülen büyüklükler gibi boş veriler `null` olarak
+ * değil, hiç dönmez.
+ */
+const compact = (record) =>
+  Object.fromEntries(
+    Object.entries(record).filter(([, value]) => value !== null && value !== undefined),
+  );
+
+/** Tek bir tablo satırını olay (event) nesnesine çevirir. */
+function parseRow(line) {
+  const head = ROW_START.exec(line);
+  if (!head) return null;
+
+  const [, date, time, rest] = head;
+  const body = NUMBERS.exec(rest);
+  if (!body) return null;
+
+  const latitude = toNumber(body[1]);
+  const longitude = toNumber(body[2]);
+  const depthKm = toNumber(body[3]);
+  const md = toNumber(body[4]);
+  const ml = toNumber(body[5]);
+  const mw = toNumber(body[6]);
+
+  // Geçerli bir koordinat yoksa satırı atla.
+  if (latitude === null || longitude === null) return null;
+
+  // Yer adı ile çözüm niteliği arasında en az iki boşluk vardır.
+  let tail = body[7].trim();
+
+  // Revize edilen satırların sonunda "REVIZE01   (2026.09.24 10:40:55)" gibi
+  // bir damga bulunur; önce onu ayırırız.
+  let revisedAt = null;
+  const stamp = /\s{2,}\((\d{4}\.\d{2}\.\d{2} \d{2}:\d{2}:\d{2})\)\s*$/.exec(tail);
+  if (stamp) {
+    revisedAt = stamp[1];
+    tail = tail.slice(0, stamp.index).trim();
+  }
+
+  const split = /^(.*?)\s{2,}(\S+)$/.exec(tail);
+  const location = (split ? split[1] : tail).trim();
+  const solutionType = split ? split[2] : null;
+
+  // Kandilli zamanları Türkiye saat dilimindedir (UTC+03:00, yaz saati uygulanmaz).
+  const iso = `${date.replace(/\./g, "-")}T${time}+03:00`;
+  const dateObj = new Date(iso);
+
+  // Kullanılan büyüklük: tercihen ML, yoksa Mw, yoksa MD.
+  const magnitude = ml ?? mw ?? md;
+
+  return compact({
+    id: createHash("sha1").update(line).digest("hex").slice(0, 16),
+    date,
+    time,
+    datetime: dateObj.toISOString(),
+    timestamp: Math.floor(dateObj.getTime() / 1000),
+    latitude,
+    longitude,
+    depthKm,
+    magnitude,
+    magnitudeType: ml !== null ? "ML" : mw !== null ? "Mw" : md !== null ? "MD" : null,
+    md,
+    ml,
+    mw,
+    location,
+    region: extractRegion(location),
+    solutionType,
+    revised: revisedAt !== null,
+    revisedAt,
+  });
+}
+
+/**
+ * KOERI sayfa kaynağından tüm deprem kayıtlarını çıkarır.
+ * @param {string} html Kaynak sayfanın metni (windows-1254 çözümlenmiş).
+ * @returns {Array<object>} En yeniden en eskiye sıralı olay listesi.
+ */
+export function parseKandilliPage(html) {
+  const events = [];
+
+  for (const rawLine of String(html).split(/\r?\n/)) {
+    // trimEnd: sondaki satır sonu ve olası kırık HTML artıkları temizlenir.
+    const event = parseRow(rawLine.trimEnd());
+    if (event) events.push(event);
+  }
+
+  return events;
+}

package/src/lib/errors.js

@@ -0,0 +1,11 @@
+/** HTTP durum kodu taşıyan hata sınıfı. */
+export class HttpError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+  }
+}
+
+/** 400 - geçersiz istek parametresi */
+export const badRequest = (message) => new HttpError(400, message);

package/src/lib/filters.js

@@ -0,0 +1,189 @@
+/**
+ * Deprem listesi üzerinde filtreleme, sıralama ve sayfalama.
+ * Tüm sorgu parametreleri isteğe bağlıdır ve doğrulama hatalarında 400 döner.
+ */
+
+import { badRequest } from "./errors.js";
+
+const MAX_LIMIT = 500;
+
+/** Türkçe karakterleri ASCII'ye indirger; "MUĞLA" ile "mugla" eşleşsin diye. */
+const CHAR_MAP = {
+  I: "i", İ: "i", ı: "i",
+  Ş: "s", ş: "s",
+  Ğ: "g", ğ: "g",
+  Ü: "u", ü: "u",
+  Ö: "o", ö: "o",
+  Ç: "c", ç: "c",
+  Â: "a", â: "a",
+  Î: "i", î: "i",
+  Û: "u", û: "u",
+};
+
+export function normalizeText(value) {
+  return String(value ?? "")
+    .replace(/[IİıŞşĞğÜüÖöÇçÂâÎîÛû]/g, (ch) => CHAR_MAP[ch])
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "");
+}
+
+/** Sorgu değerini sayıya çevirir; geçersizse 400 fırlatır. */
+function readNumber(query, key) {
+  const raw = query[key];
+  if (raw === undefined || raw === "") return null;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    throw badRequest(`"${key}" geçerli bir sayı olmalı. Gelen değer: ${raw}`);
+  }
+  return value;
+}
+
+/**
+ * Tarih parametresini Date'e çevirir.
+ * Sadece "YYYY-MM-DD" verildiğinde TR saat dilimine göre gün başı/sonu kabul edilir.
+ */
+function readDate(query, key, endOfDay) {
+  const raw = query[key];
+  if (raw === undefined || raw === "") return null;
+
+  let value = String(raw).trim();
+
+  // Query string'de "+" işareti boşluk olarak çözüldüğü için
+  // "2026-09-28T12:00:00+03:00" geleni "… 03:00" olur; offset'i geri kazan.
+  value = value.replace(
+    /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?)\s+(\d{2}:\d{2})$/,
+    "$1+$2",
+  );
+
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    value = `${value}T${endOfDay ? "23:59:59" : "00:00:00"}+03:00`;
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw badRequest(
+      `"${key}" geçerli bir tarih olmalı (YYYY-MM-DD veya ISO 8601). Gelen değer: ${raw}`,
+    );
+  }
+  return parsed;
+}
+
+function readList(query, key, allowed) {
+  const raw = query[key];
+  if (raw === undefined || raw === "") return null;
+  if (!allowed.includes(raw)) {
+    throw badRequest(`"${key}" şunlardan biri olmalı: ${allowed.join(", ")}`);
+  }
+  return raw;
+}
+
+const rangeFilter = (items, field, min, max) => {
+  if (min !== null) items.push((e) => (e[field] ?? -Infinity) >= min);
+  if (max !== null) items.push((e) => (e[field] ?? Infinity) <= max);
+};
+
+/**
+ * @param {Array<object>} events Ham kayıtlar
+ * @param {object} query Express query nesnesi
+ * @returns {{ items: Array, total: number, limit: number, offset: number, applied: object }}
+ */
+export function applyFilters(events, query) {
+  const minMag = readNumber(query, "minMag");
+  const maxMag = readNumber(query, "maxMag");
+  const minDepth = readNumber(query, "minDepth");
+  const maxDepth = readNumber(query, "maxDepth");
+  const minLat = readNumber(query, "minLat");
+  const maxLat = readNumber(query, "maxLat");
+  const minLon = readNumber(query, "minLon");
+  const maxLon = readNumber(query, "maxLon");
+
+  const start = readDate(query, "start", false);
+  const end = readDate(query, "end", true);
+  const search = query.q ? normalizeText(query.q) : null;
+
+  const sort = readList(query, "sort", ["date", "mag", "depth"]) ?? "date";
+  const order = readList(query, "order", ["asc", "desc"]) ?? "desc";
+
+  if (start && end && start > end) {
+    throw badRequest('"start", "end" tarihinden sonra olamaz');
+  }
+
+  const limitRaw = readNumber(query, "limit");
+  const offsetRaw = readNumber(query, "offset");
+
+  // "limit" verilmezse filtrede eşleşen TÜM kayıtlar döndürülür.
+  const limit =
+    limitRaw === null
+      ? null
+      : Math.min(Math.max(Math.trunc(limitRaw), 1), MAX_LIMIT);
+  const offset = Math.max(Math.trunc(offsetRaw ?? 0), 0);
+
+  // --- Filtre zinciri ---
+  const predicates = [];
+
+  if (search) {
+    predicates.push((e) => normalizeText(e.location).includes(search));
+  }
+  if (start) predicates.push((e) => e.timestamp * 1000 >= start.getTime());
+  if (end) predicates.push((e) => e.timestamp * 1000 <= end.getTime());
+
+  rangeFilter(predicates, "magnitude", minMag, maxMag);
+  rangeFilter(predicates, "depthKm", minDepth, maxDepth);
+  rangeFilter(predicates, "latitude", minLat, maxLat);
+  rangeFilter(predicates, "longitude", minLon, maxLon);
+
+  const filtered = predicates.length
+    ? events.filter((event) => predicates.every((test) => test(event)))
+    : events.slice();
+
+  // --- Sıralama ---
+  const getter =
+    sort === "mag"
+      ? (e) => e.magnitude ?? -Infinity
+      : sort === "depth"
+        ? (e) => e.depthKm ?? Infinity
+        : (e) => e.timestamp;
+
+  const direction = order === "asc" ? 1 : -1;
+  filtered.sort((a, b) => {
+    const va = getter(a);
+    const vb = getter(b);
+    return va === vb ? 0 : va > vb ? direction : -direction;
+  });
+
+  const total = filtered.length;
+  const items =
+    limit === null ? filtered.slice(offset) : filtered.slice(offset, offset + limit);
+
+  // Sadece kullanıcı tarafından gerçekten gönderilen filtreler döndürülür;
+  // kullanılmayan parametreler null olarak geri yazılmaz.
+  const applied = { sort, order };
+  const put = (key, value) => {
+    if (value !== null) applied[key] = value;
+  };
+
+  put("minMag", minMag);
+  put("maxMag", maxMag);
+  put("minDepth", minDepth);
+  put("maxDepth", maxDepth);
+  put("minLat", minLat);
+  put("maxLat", maxLat);
+  put("minLon", minLon);
+  put("maxLon", maxLon);
+  // Tarih filtreleri, kullanıcı ne yazdıysa aynen geri yazılır (UTC'ye çevrilmez).
+  const echoDate = (raw, parsed) =>
+    !parsed ? null : /^\d{4}-\d{2}-\d{2}$/.test(raw) ? raw : parsed.toISOString();
+
+  put("start", echoDate(query.start ?? "", start));
+  put("end", echoDate(query.end ?? "", end));
+  put("q", query.q ?? null);
+
+  return {
+    items,
+    total,
+    limit,
+    offset,
+    applied,
+  };
+}

package/src/routes/depremler.js

@@ -0,0 +1,96 @@
+import { Router } from "express";
+import { getEvents } from "../kandilli/client.js";
+import { applyFilters } from "../lib/filters.js";
+import { badRequest } from "../lib/errors.js";
+
+export const depremlerRouter = Router();
+
+/**
+ * GET /api/depremler
+ *
+ * Kandilli Rasathanesi'ndeki son depremleri filtreleyerek listeler.
+ *
+ * Query parametreleri (hepsi isteğe bağlı):
+ *   minMag, maxMag     büyüklük aralığı
+ *   minDepth, maxDepth  derinlik (km) aralığı
+ *   minLat, maxLat      enlem aralığı
+ *   minLon, maxLon      boylam aralığı
+ *   q                   yer adında arama (türkçe karakter duyarsız)
+ *   start, end          tarih aralığı (YYYY-MM-DD veya ISO 8601)
+ *   limit               kaç kayıt döneceği; verilmezse eşleşen HEPSİ (en fazla 500)
+ *   offset              atlanacak kayıt sayısı
+ *   sort                date | mag | depth   (varsayılan date)
+ *   order               asc | desc           (varsayılan desc)
+ *   fresh=true          cache'i atlayıp kaynağı yeniden çeker
+ */
+depremlerRouter.get("/depremler", async (req, res) => {
+  const force = req.query.fresh === "true";
+
+  if (force && Object.keys(req.query).some((k) => k !== "fresh")) {
+    throw badRequest('"fresh=true" diğer filtrelerle birlikte kullanılamaz');
+  }
+
+  const snapshot = await getEvents({ force });
+  const { items, total, limit, offset, applied } = applyFilters(
+    snapshot.events,
+    req.query,
+  );
+
+  const result = {
+    source: "Boğaziçi Üniversitesi Kandilli Rasathanesi (KOERI)",
+    sourceUrl: snapshot.sourceUrl,
+    attribution:
+      "Veri kaynağı: KOERI-Bölgesel Deprem-Tsunami İzleme ve Değerlendirme Merkezi. " +
+      "Ticari kullanım için Boğaziçi Üniversitesi Rektörlüğü'nden izin alınmalıdır.",
+    updated: snapshot.fetchedAt,
+    stale: snapshot.stale,
+    total,
+    count: items.length,
+  };
+
+  // "limit" verilmediyse alan hiç görünmez (hepsi gönderilmiş demektir).
+  if (limit !== null) result.limit = limit;
+
+  Object.assign(result, {
+    offset,
+    filters: applied,
+    data: items,
+  });
+
+  // Kaynak erişilemiyorsa uyarı eklenir; sorun yoksa alan hiç görünmez.
+  if (snapshot.stale) {
+    result.warning = `Kaynak şu anda erişilemiyor, en son başarılı veri gösteriliyor: ${snapshot.error}`;
+  }
+
+  res.json(result);
+});
+
+/**
+ * GET /api/depremler/ozet
+ * Filtre uygulanmamış; liste künyesi ve büyüklük dağılımı.
+ */
+depremlerRouter.get("/depremler/ozet", async (req, res) => {
+  const snapshot = await getEvents();
+  const events = snapshot.events;
+
+  const magnitudeBuckets = { "0-1": 0, "1-2": 0, "2-3": 0, "3-4": 0, "4+": 0 };
+  for (const e of events) {
+    const m = e.magnitude ?? 0;
+    if (m >= 4) magnitudeBuckets["4+"] += 1;
+    else magnitudeBuckets[`${Math.floor(m)}-${Math.floor(m) + 1}`] += 1;
+  }
+
+  res.json({
+    source: "Boğaziçi Üniversitesi Kandilli Rasathanesi (KOERI)",
+    updated: snapshot.fetchedAt,
+    stale: snapshot.stale,
+    count: events.length,
+    newest: events[0] ?? null,
+    oldest: events.at(-1) ?? null,
+    strongest: events.reduce(
+      (max, e) => (!max || (e.magnitude ?? -1) > (max.magnitude ?? -1) ? e : max),
+      null,
+    ),
+    magnitudeBuckets,
+  });
+});

package/src/server.js

@@ -0,0 +1,80 @@
+import express from "express";
+import { depremlerRouter } from "./routes/depremler.js";
+import { getEvents } from "./kandilli/client.js";
+import { HttpError } from "./lib/errors.js";
+
+export function createApp() {
+  const app = express();
+
+  app.disable("x-powered-by");
+  app.use(express.json());
+
+  // Tarayıcıdan (Leaflet vb.) erişilebilsin diye basit CORS.
+  app.use((req, res, next) => {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET,OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    if (req.method === "OPTIONS") return res.sendStatus(204);
+    next();
+  });
+
+  app.get("/", (_req, res) => {
+    res.json({
+      name: "Deprem API",
+      description:
+        "Kandilli Rasathanesi (KOERI) son depremlerini JSON olarak sunar.",
+      endpoints: {
+        "GET /api/depremler": "Filtrelenebilir deprem listesi",
+        "GET /api/depremler/ozet": "Liste özeti ve büyüklük dağılımı",
+        "GET /api/saglik": "Servis ve kaynak durumu",
+      },
+      examples: [
+        "/api/depremler?minMag=4&limit=20",
+        "/api/depremler?q=marmara&minDepth=0&maxDepth=30",
+        "/api/depremler?start=2026-09-28&end=2026-09-29&sort=mag&order=desc",
+        "/api/depremler?minLat=38&maxLat=42&minLon=26&maxLon=32",
+      ],
+    });
+  });
+
+  app.use("/api", depremlerRouter);
+
+  app.get("/api/saglik", async (_req, res) => {
+    try {
+      const snapshot = await getEvents();
+      res.json({
+        status: "ok",
+        source: snapshot.sourceUrl,
+        records: snapshot.events.length,
+        updated: snapshot.fetchedAt,
+        cacheExpiresAt: new Date(snapshot.expiresAt).toISOString(),
+        stale: snapshot.stale,
+        error: snapshot.error,
+      });
+    } catch (error) {
+      res.status(503).json({
+        status: "error",
+        message: "Kandilli kaynağına şu anda ulaşılamıyor",
+        detail: error.message,
+      });
+    }
+  });
+
+  app.use((_req, res) => {
+    res.status(404).json({ error: "Uç nokta bulunamadı", path: _req.originalUrl });
+  });
+
+  // Hata yakalayıcı — en sonda olmalı.
+  app.use((err, _req, res, _next) => {
+    if (err instanceof HttpError) {
+      return res.status(err.status).json({ error: err.message });
+    }
+    console.error("[hata]", err);
+    res.status(500).json({
+      error: "Sunucu hatası",
+      detail: err.message,
+    });
+  });
+
+  return app;
+}