🌋 Earthquake API

Real-time earthquake data from Turkey's two major sources — clean, fast, open.

Kandilli Rasathanesi (Boğaziçi Üniversitesi) · AFAD (Afet ve Acil Durum Yönetimi Başkanlığı)

Canlı veri · 5 dakikada bir otomatik güncelleme · GeoJSON uyumlu çıktı · CORS açık

🇹🇷 Türkçe

🎯 Nedir Bu?

Earthquake API, Türkiye'nin iki büyük deprem veri kaynağından — Kandilli Rasathanesi ve AFAD — canlı veri çeken, 5 dakikada bir otomatik güncellenen ve GeoJSON uyumlu temiz bir JSON çıktısı sunan hafif bir Flask API'sidir.

Kurulumu saniyeler sürer, harici veritabanı gerektirmez, tüm veriyi bellekte tutar ve web uygulamalarınıza, mobil uygulamalarınıza, harita dashboard'larınıza veya GIS araçlarınıza (Leaflet, Mapbox, QGIS) doğrudan bağlanabilir.

Neden Earthquake API? Çünkü iki ayrı kaynağı tek bir tutarlı şemada birleştirir, bir kaynak düşse bile diğeri çalışmaya devam eder ve thread-safe bir mimariyle Flask'ı asla bloke etmez.

💡 Neden Bu API?

🌍	⏱️	🔎	📦
İki kaynak, tek API	Otomatik güncelleme	Zengin filtreleme	GeoJSON uyumlu
Kandilli + AFAD aynı şemada	Her 5 dakikada bir	Konum, büyüklük veya ikisi	Leaflet, Mapbox, QGIS

🧵	🛡️	❤️	🪶
Thread-safe mimari	Hata izolasyonu	`/health` endpoint	Hafif
`threading.Lock` ile korunur	Bir kaynak düşse diğeri çalışır	Canlılık + tazelik kontrolü	Flask + BS4 + schedule

✨ Özellikler

🌍 Veri Kaynakları

✅ Kandilli Rasathanesi canlı akışı
✅ AFAD resmi akışı
✅ Her iki kaynak için tek ve tutarlı JSON şeması
✅ Türkçe karakter destekli UTF-8 çıktı

⏱️ Otomatik Güncelleme

✅ Arka planda thread'li scheduler
✅ 5 dakikada bir otomatik yenileme
✅ Başlangıçta anlık ilk yükleme
✅ Flask'ı bloke etmeyen daemon=True thread

🔎 Filtreleme

✅ Konuma göre — ?location=Izmir
✅ Büyüklüğe göre — ?size=4.5
✅ İkisi birden — ?size=4&location=Ankara
✅ Kaynak seçimi — ?type=afad

📦 Çıktı Formatı

✅ GeoJSON uyumlu FeatureCollection
✅ Her deprem: md / ml / mw büyüklükleri
✅ geometry: { type: "Point", coordinates: [lon, lat, depth] }
✅ Metadata: generated, last_updated, count, errors

🛡️ Güvenilirlik

✅ Per-source hata izolasyonu
✅ Thread-safe buffer (threading.Lock)
✅ Timeout + User-Agent ile güvenli istekler
✅ JSON dönen 404 ve 500 handler'ları

🎨 Geliştirici Deneyimi

✅ /health endpoint'i
✅ Açık CORS politikası
✅ Cache-Control: max-age=60
✅ MIT lisansı, ticari kullanıma uygun

🛠️ Teknoloji Yığını

Katman	Teknoloji
Backend	Python 3.10+, Flask 3.0
HTML Parsing	BeautifulSoup4
Zamanlayıcı	`schedule` + `threading`
HTTP Client	`urllib` (standart kütüphane)
Eşzamanlılık	`threading.Lock` (thread-safe buffer)
Çıktı	JSON (GeoJSON uyumlu)

🚀 Kurulum

Gereksinimler

Python 3.10 veya üzeri
pip

Adım Adım

# 1. Repoyu klonla
git clone https://github.com/mdaedalus/Earthquake-api.git
cd Earthquake-api

# 2. Sanal ortam oluştur
python -m venv venv

# Windows:
venv\Scripts\activate

# macOS/Linux:
source venv/bin/activate

# 3. Bağımlılıkları yükle
pip install -r requirements.txt

# 4. API'yi başlat
python app.py

Tarayıcınızda açın: http://localhost:5000

Not: requests kütüphanesi kullanılmıyor — HTTP istekleri standart kütüphanedeki urllib ile yapılıyor.

🔌 API Kullanımı

Kök Endpoint

GET /

Parametre	Tip	Açıklama	Örnek
`type`	string	Kaynak: `kandilli` (varsayılan) veya `afad`	`?type=afad`
`location`	string	Şehir / ilçe filtresi (case-insensitive)	`?location=Izmir`
`size`	float	Minimum büyüklük (md/ml/mw arasından en büyüğü)	`?size=4.5`

Örnek İstekler

# Kandilli'den son depremler
curl http://localhost:5000/

# AFAD'dan son depremler
curl http://localhost:5000/?type=afad

# İzmir'deki depremler
curl http://localhost:5000/?location=Izmir

# 4.0 ve üzeri büyüklükteki depremler
curl http://localhost:5000/?size=4

# Ankara'da 3.0 ve üzeri depremler
curl http://localhost:5000/?size=3&location=Ankara

# Sağlık kontrolü
curl http://localhost:5000/health

Örnek Yanıt

{
  "type": "FeatureCollection",
  "metadata": {
    "generated": "2025-01-15 14:32:00 UTC",
    "last_updated": "2025-01-15 14:30:00 UTC",
    "title": "Earthquake API",
    "api_version": "1.0.0",
    "source": "kandilli",
    "count": 42,
    "errors": {}
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "mag": { "md": 0, "ml": 4.2, "mw": 0 },
        "place": "IZMIR KORFEZI",
        "time": 1736958720,
        "updated": 1736958720,
        "status": "İlksel",
        "type": "earthquake",
        "title": "M 4.2 - IZMIR KORFEZI",
        "depth": 7.3
      },
      "geometry": {
        "type": "Point",
        "coordinates": [26.85, 38.42, 7.3]
      },
      "id": "kandilli-1736958720-483921",
      "source": "kandilli"
    }
  ]
}

Health Endpoint

GET /health

{
  "status": "ok",
  "last_updated": "2025-01-15 14:30:00 UTC",
  "kandilli_count": 42,
  "afad_count": 38,
  "errors": {}
}

🗺️ Kullanım Akışı

Adres	Yaptığı İş
`/`	Tüm depremler (varsayılan: Kandilli)
`/?type=afad`	AFAD kaynağından depremler
`/?type=kandilli`	Kandilli kaynağından depremler
`/?location=<il>`	Belirtilen ildeki depremler
`/?size=<büyüklük>`	Belirtilen büyüklük ve üzeri
`/?size=<b>&location=<il>`	Hem konum hem büyüklük filtresi
`/health`	Canlılık ve veri tazeliği kontrolü

📂 Proje Yapısı

Earthquake-api/
├── app.py                         # Ana Flask uygulaması
├── requirements.txt
├── LICENSE                        # MIT
├── README.md
├── .gitignore
└── img/                           # 📸 Ekran görüntüleri

🔧 Özelleştirme

⏱️ Güncelleme Sıklığı

update_data() çağrısının sıklığını değiştirmek için:

UPDATE_INTERVAL_MINUTES = 5    # 5 dakika
UPDATE_INTERVAL_MINUTES = 1    # 1 dakika

🌐 Port ve Host

app.run() satırını düzenleyin:

app.run(host="0.0.0.0", port=8080, debug=False)

🔒 CORS Politikası

Tüm domain'lere açmak yerine belirli bir domain'e kısıtlamak için:

response.headers["Access-Control-Allow-Origin"] = "https://siteniz.com"

🔎 Filtre Genişletme

Yeni filtreler eklemek için index() fonksiyonundaki if/elif zincirini genişletin:

depth = request.args.get("depth")
if depth:
    data = [d for d in data if d["properties"]["depth"] >= float(depth)]

🗺️ Yol Haritası

🤝 Katkıda Bulunma

Katkılarınızı bekliyoruz! Büyük değişiklikler için önce bir issue açın.

# Fork → Clone → Branch → Commit → Push → PR
git checkout -b feature/yeni-ozellik
git commit -m "feat: yeni özellik eklendi"
git push origin feature/yeni-ozellik

Commit Kuralları

Prefix	Anlamı
`feat:`	yeni özellik
`fix:`	hata düzeltme
`docs:`	dokümantasyon
`style:`	kod formatı
`refactor:`	yeniden düzenleme
`test:`	test ekleme

⚠️ Yasal Uyarı

Bu API, kamuya açık kaynaklardan (Kandilli Rasathanesi ve AFAD) veri çeker. Resmî bir kurum değildir ve acil durum kararları için tek başına kullanılmamalıdır. Kritik bilgiler için lütfen resmî kaynaklara başvurun:

🔗 Kandilli Rasathanesi
🔗 AFAD Deprem Dairesi

🇬🇧 English

🎯 What Is This?

Earthquake API is a lightweight Flask API that scrapes live earthquake data from two major Turkish sources — Kandilli Observatory and AFAD — refreshes automatically every 5 minutes, and exposes a clean GeoJSON-compatible JSON output.

It sets up in seconds, requires no external database, holds all data in memory, and plugs directly into your web apps, mobile apps, map dashboards, or GIS tools (Leaflet, Mapbox, QGIS).

Why Earthquake API? Because it merges two sources into one consistent schema, keeps working even if one source goes down, and never blocks Flask thanks to a thread-safe architecture.

💡 Why This API?

🌍	⏱️	🔎	📦
Two sources, one API	Auto-refresh	Rich filtering	GeoJSON compatible
Kandilli + AFAD in one schema	Every 5 minutes	Location, magnitude, or both	Leaflet, Mapbox, QGIS

🧵	🛡️	❤️	🪶
Thread-safe	Fault isolation	`/health` endpoint	Lightweight
Protected by `threading.Lock`	One source down, other keeps running	Liveness + freshness check	Flask + BS4 + schedule

✨ Features

🌍 Data Sources

✅ Kandilli Observatory live feed
✅ AFAD official feed
✅ Single, consistent JSON schema for both
✅ UTF-8 output with full Turkish support

⏱️ Auto-Refresh

✅ Background threaded scheduler
✅ Every 5 minutes automatic refresh
✅ Instant first load on startup
✅ daemon=True thread that doesn't block Flask

🔎 Filtering

✅ By location — ?location=Izmir
✅ By magnitude — ?size=4.5
✅ Both — ?size=4&location=Ankara
✅ Source selection — ?type=afad

📦 Output Format

✅ GeoJSON-compatible FeatureCollection
✅ Per quake: md / ml / mw magnitudes
✅ geometry: { type: "Point", coordinates: [lon, lat, depth] }
✅ Metadata: generated, last_updated, count, errors

🛡️ Reliability

✅ Per-source error isolation
✅ Thread-safe buffer (threading.Lock)
✅ Timeout + User-Agent for safe requests
✅ JSON 404 & 500 handlers

🎨 Developer Experience

✅ /health endpoint
✅ Open CORS policy
✅ Cache-Control: max-age=60
✅ MIT license, commercial use OK

🛠️ Tech Stack

Layer	Technology
Backend	Python 3.10+, Flask 3.0
HTML Parsing	BeautifulSoup4
Scheduler	`schedule` + `threading`
HTTP Client	`urllib` (standard library)
Concurrency	`threading.Lock` (thread-safe buffer)
Output	JSON (GeoJSON-compatible)

🚀 Installation

Requirements

Python 3.10 or higher
pip

Step by Step

# 1. Clone the repo
git clone https://github.com/mdaedalus/Earthquake-api.git
cd Earthquake-api

# 2. Create virtual environment
python -m venv venv

# Windows:
venv\Scripts\activate

# macOS/Linux:
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Start the API
python app.py

Open in your browser: http://localhost:5000

Note: requests is not used — HTTP calls go through the standard library's urllib.

🔌 API Usage

Root Endpoint

GET /

Parameter	Type	Description	Example
`type`	string	Source: `kandilli` (default) or `afad`	`?type=afad`
`location`	string	City / district filter (case-insensitive)	`?location=Izmir`
`size`	float	Minimum magnitude (largest of md/ml/mw)	`?size=4.5`

Example Requests

# Latest earthquakes from Kandilli
curl http://localhost:5000/

# Latest earthquakes from AFAD
curl http://localhost:5000/?type=afad

# Earthquakes in Izmir
curl http://localhost:5000/?location=Izmir

# Earthquakes of magnitude 4.0 and above
curl http://localhost:5000/?size=4

# Earthquakes of magnitude 3.0+ in Ankara
curl http://localhost:5000/?size=3&location=Ankara

# Health check
curl http://localhost:5000/health

Example Response

{
  "type": "FeatureCollection",
  "metadata": {
    "generated": "2025-01-15 14:32:00 UTC",
    "last_updated": "2025-01-15 14:30:00 UTC",
    "title": "Earthquake API",
    "api_version": "1.0.0",
    "source": "kandilli",
    "count": 42,
    "errors": {}
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "mag": { "md": 0, "ml": 4.2, "mw": 0 },
        "place": "IZMIR KORFEZI",
        "time": 1736958720,
        "updated": 1736958720,
        "status": "İlksel",
        "type": "earthquake",
        "title": "M 4.2 - IZMIR KORFEZI",
        "depth": 7.3
      },
      "geometry": {
        "type": "Point",
        "coordinates": [26.85, 38.42, 7.3]
      },
      "id": "kandilli-1736958720-483921",
      "source": "kandilli"
    }
  ]
}

Health Endpoint

GET /health

{
  "status": "ok",
  "last_updated": "2025-01-15 14:30:00 UTC",
  "kandilli_count": 42,
  "afad_count": 38,
  "errors": {}
}

🗺️ Usage Flow

URL	What It Does
`/`	All earthquakes (default: Kandilli)
`/?type=afad`	Earthquakes from AFAD
`/?type=kandilli`	Earthquakes from Kandilli
`/?location=<city>`	Earthquakes in the given city
`/?size=<magnitude>`	Earthquakes at or above magnitude
`/?size=<m>&location=<city>`	Both filters combined
`/health`	Liveness & data freshness check

📂 Project Structure

Earthquake-api/
├── app.py                         # Main Flask app
├── requirements.txt
├── LICENSE                        # MIT
├── README.md
├── .gitignore
└── img/                           # 📸 Screenshots

🔧 Customization

⏱️ Refresh Interval

To change how often update_data() runs:

UPDATE_INTERVAL_MINUTES = 5    # 5 minutes
UPDATE_INTERVAL_MINUTES = 1    # 1 minute

🌐 Port and Host

Edit the app.run() line:

app.run(host="0.0.0.0", port=8080, debug=False)

🔒 CORS Policy

To restrict CORS to a specific domain instead of opening it to all:

response.headers["Access-Control-Allow-Origin"] = "https://yourdomain.com"

🔎 Extending Filters

Add new filters by extending the if/elif chain in index():

depth = request.args.get("depth")
if depth:
    data = [d for d in data if d["properties"]["depth"] >= float(depth)]

🗺️ Roadmap

🤝 Contributing

Contributions are welcome! For major changes, please open an issue first.

# Fork → Clone → Branch → Commit → Push → PR
git checkout -b feature/new-feature
git commit -m "feat: added new feature"
git push origin feature/new-feature

Commit Conventions

Prefix	Meaning
`feat:`	new feature
`fix:`	bug fix
`docs:`	documentation
`style:`	code formatting
`refactor:`	refactoring
`test:`	adding tests

⚠️ Disclaimer

This API scrapes data from publicly available sources (Kandilli Observatory and AFAD). It is not an official body and must not be used as the sole basis for emergency decisions. Always refer to official sources for critical information:

🔗 Kandilli Observatory
🔗 AFAD Earthquake Department

📄 License

This project is licensed under the MIT License.
See the LICENSE file for details.

👨‍💻 Author

Emin Neşat Gürses

⭐ If you like this project, don't forget to star it!

Made with ❤️ in Turkey

Latest commit

History

Folders and files

Repository files navigation

🌋 Earthquake API

Real-time earthquake data from Turkey's two major sources — clean, fast, open.

🇹🇷 Türkçe

🎯 Nedir Bu?

💡 Neden Bu API?

✨ Özellikler

🌍 Veri Kaynakları

⏱️ Otomatik Güncelleme

🔎 Filtreleme

📦 Çıktı Formatı

🛡️ Güvenilirlik

🎨 Geliştirici Deneyimi

🛠️ Teknoloji Yığını

🚀 Kurulum

Gereksinimler

Adım Adım

🔌 API Kullanımı

Kök Endpoint

Örnek İstekler

Örnek Yanıt

Health Endpoint

🗺️ Kullanım Akışı

📂 Proje Yapısı

🔧 Özelleştirme

🗺️ Yol Haritası

🤝 Katkıda Bulunma

Commit Kuralları

⚠️ Yasal Uyarı

🇬🇧 English

🎯 What Is This?

💡 Why This API?

✨ Features

🌍 Data Sources

⏱️ Auto-Refresh

🔎 Filtering

📦 Output Format

🛡️ Reliability

🎨 Developer Experience

🛠️ Tech Stack

🚀 Installation

Requirements

Step by Step

🔌 API Usage

Root Endpoint

Example Requests

Example Response

Health Endpoint

🗺️ Usage Flow

📂 Project Structure

🔧 Customization

🗺️ Roadmap

🤝 Contributing

Commit Conventions

⚠️ Disclaimer

📄 License

👨‍💻 Author

⭐ If you like this project, don't forget to star it!

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages