API Dokümantasyonu - Jaharia - Türkiye Deprem İzleme Monitörü

📋 İçindekiler

Genel Bakış
Kimlik Doğrulama
WebSocket API
REST API
Kod Örnekleri
Entegrasyon
Topluluk

📖 Genel Bakış

Türkiye Deprem Anlık İzleme Sistemi, Kandilli Rasathanesi verilerini kullanarak gerçek zamanlı deprem bilgileri sunan bir API platformudur. Sistem WebSocket ve REST API üzerinden veri sağlar.

Özellikler

⚡ Gerçek Zamanlı Veri: WebSocket ile anlık deprem bildirimleri
🔐 Güvenli Erişim: Token tabanlı kimlik doğrulama (Laravel Sanctum)
📊 REST API: HTTP üzerinden deprem verilerine erişim
🌍 Konum Filtreleme: Koordinat bazlı arama ve filtreleme
📈 İstatistikler: Günlük, haftalık ve toplam deprem istatistikleri

Veri Kaynağı

Veriler Boğaziçi Üniversitesi Kandilli Rasathanesi ve Deprem Araştırma Enstitüsü Bölgesel Deprem-Tsunami İzleme Ve Değerlendirme Merkezi'nden gelmektedir.

ℹ️ Bilgi: Sistem 5 saniyede bir otomatik olarak Kandilli API'sinden veri çekmektedir.

🔐 Kimlik Doğrulama

Tüm API endpoint'leri (public endpoint'ler hariç) Laravel Sanctum token tabanlı kimlik doğrulama kullanır.

API Anahtarı Alma

Admin paneline giriş yapın: /admin
Kullanıcılar bölümünden yeni bir kullanıcı oluşturun
Kullanıcıya "API Anahtarı Oluştur" butonuna tıklayın
Token adı belirleyin (örn: "production", "development")
Oluşturulan token'ı güvenli bir yere kaydedin

⚠️ Önemli: Token sadece bir kez gösterilir. Mutlaka güvenli bir yere kaydedin!

Token Kullanımı

API isteklerinde token'ı Authorization header'ında Bearer token olarak gönderin:

Authorization: Bearer YOUR_API_TOKEN

WebSocket bağlantısı için token'ı yetkilendirme endpoint'ine gönderin (detaylar aşağıda).

📡 WebSocket API

Sistem Pusher protokolü kullanarak WebSocket üzerinden gerçek zamanlı deprem bildirimleri sağlar.

Yetkilendirme Endpoint

POST /api/ws/auth

WebSocket kanallarına abone olmak için bu endpoint'i kullanın.

İstek Parametreleri

Parametre	Tip	Açıklama	Gerekli
`channel_name`	string	Abone olunacak kanal adı	Gerekli
`socket_id`	string	Pusher socket ID	Gerekli

Yetkilendirme Yöntemleri

Yöntem 1: Bearer Token (Header)

Authorization: Bearer YOUR_API_TOKEN

Yöntem 2: API Key (Body)

api_key=YOUR_API_TOKEN

Kullanılabilir Kanallar

Kanal Adı	Açıklama	Tip
`private-earthquakes.tr`	Türkiye için anlık deprem yayınları	Private
`presence-earthquakes.tr`	Presence kanalı (kullanıcı bilgileri ile)	Presence
`private-user.{id}`	Kullanıcıya özel kanal (kullanıcı ID'si ile)	Private

Event: earthquake.detected

Yeni bir deprem tespit edildiğinde earthquake.detected event'i yayınlanır.

Event Payload Yapısı

{
  "id": "kandilli_20250103123456",
  "magnitude": 3.4,
  "depth_km": 7.2,
  "lat": 39.123,
  "lon": 27.456,
  "place": "İstanbul",
  "source": "kandilli",
  "occurred_at": "2025-01-03T12:34:56+03:00",
  "time": 1730612345678
}

Alanlar

Alan	Tip	Açıklama
`id`	string	Deprem benzersiz ID'si
`magnitude`	float	Deprem büyüklüğü (Richter ölçeği)
`depth_km`	float	Derinlik (kilometre)
`lat`	float	Enlem (latitude)
`lon`	float	Boylam (longitude)
`place`	string	Konum adı (şehir/il)
`source`	string	Veri kaynağı (kandilli, koeri, vb.)
`occurred_at`	string	Deprem zamanı (ISO 8601 format)
`time`	integer	Deprem zamanı (Unix timestamp - milliseconds)

🌐 REST API

1. Public Endpoint - Son Depremler

GET /api/public/earthquakes

API anahtarı gerektirmeyen public endpoint. Son depremleri listeler.

Query Parametreleri

Parametre	Tip	Açıklama	Varsayılan	Gerekli
`limit`	integer	Döndürülecek kayıt sayısı (1-50 arası)	10	Opsiyonel

Örnek İstek

GET /api/public/earthquakes?limit=20

Örnek Yanıt

[
  {
    "id": "kandilli_20250103123456",
    "magnitude": 3.4,
    "place": "İstanbul",
    "lat": 41.0082,
    "lon": 28.9784,
    "depth_km": 7.2,
    "occurred_at": "2025-01-03T12:34:56+03:00"
  },
  ...
]

2. Authenticated Endpoint - Gelişmiş Deprem Sorgulama

GET /api/earthquakes

API anahtarı gerektiren gelişmiş endpoint. Filtreleme ve arama özellikleri sunar.

Query Parametreleri

Parametre	Tip	Açıklama	Varsayılan	Gerekli
`limit`	integer	Döndürülecek kayıt sayısı (1-200 arası)	50	Opsiyonel
`min_mag`	float	Minimum deprem büyüklüğü filtreleme	0	Opsiyonel
`since`	string	Belirtilen tarihten sonraki depremler (YYYY-MM-DD format)	-	Opsiyonel
`near`	string	Koordinat bazlı arama (format: "lat,lon")	-	Opsiyonel
`radius_km`	float	Yakınlık araması için yarıçap (kilometre). `near` ile birlikte kullanılır.	100	Opsiyonel

Örnek İstekler

# Minimum 4.0 büyüklüğündeki depremler
GET /api/earthquakes?min_mag=4.0&limit=50
Authorization: Bearer YOUR_API_TOKEN

# Belirli bir tarihten sonraki depremler
GET /api/earthquakes?since=2025-01-01&limit=100
Authorization: Bearer YOUR_API_TOKEN

# Koordinat bazlı arama (İstanbul çevresi 50km)
GET /api/earthquakes?near=41.0082,28.9784&radius_km=50&limit=20
Authorization: Bearer YOUR_API_TOKEN

# Kombine filtreleme
GET /api/earthquakes?min_mag=3.0&since=2025-01-01&limit=50
Authorization: Bearer YOUR_API_TOKEN

Yanıt Formatı

[
  {
    "id": "kandilli_20250103123456",
    "magnitude": 3.4,
    "depth_km": 7.2,
    "lat": 41.0082,
    "lon": 28.9784,
    "place": "İstanbul",
    "source": "kandilli",
    "occurred_at": "2025-01-03T12:34:56+03:00",
    "distance_km": 12.5  // Sadece 'near' parametresi kullanıldığında
  },
  ...
]

Hata Yanıtları

HTTP Status	Açıklama
`401 Unauthorized`	Geçersiz veya eksik API token
`403 Forbidden`	Kanal için yetki yok (WebSocket)
`422 Unprocessable Entity`	Geçersiz parametre değerleri
`500 Internal Server Error`	Sunucu hatası

💻 Kod Örnekleri

JavaScript (Pusher Client)

<script src="https://js.pusher.com/8.2/pusher.min.js"></script>
<script>
  // Pusher konfigürasyonu
  const pusher = new Pusher('YOUR_PUSHER_KEY', {
    cluster: 'eu',
    authEndpoint: '/api/ws/auth',
    auth: {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
      }
    }
  });

  // Kanal aboneliği
  const channel = pusher.subscribe('private-earthquakes.tr');

  // Event dinleme
  channel.bind('earthquake.detected', function(data) {
    console.log('Yeni deprem tespit edildi:', data);
    
    // Deprem bilgilerini işle
    const magnitude = data.magnitude;
    const place = data.place;
    const time = new Date(data.occurred_at);
    
    alert(`Deprem: ${magnitude} M - ${place} - ${time.toLocaleString('tr-TR')}`);
  });

  // Bağlantı durumu
  pusher.connection.bind('connected', () => {
    console.log('WebSocket bağlantısı kuruldu');
  });

  pusher.connection.bind('disconnected', () => {
    console.log('WebSocket bağlantısı kesildi');
  });
</script>

Node.js

// npm install pusher-js

import Pusher from 'pusher-js';

const pusher = new Pusher('YOUR_PUSHER_KEY', {
  cluster: 'eu',
  authEndpoint: 'https://your-domain.com/api/ws/auth',
  auth: {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  }
});

const channel = pusher.subscribe('private-earthquakes.tr');

channel.bind('earthquake.detected', (data) => {
  console.log('Yeni deprem:', data);
  
  // Webhook gönder, veritabanına kaydet, vb.
  // ...
});

// REST API örneği
import axios from 'axios';

const response = await axios.get('https://your-domain.com/api/earthquakes', {
  params: {
    min_mag: 3.0,
    limit: 50
  },
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

console.log(response.data);

Python

# pip install pusher requests

import pusher
import requests
from datetime import datetime

# WebSocket bağlantısı
pusher_client = pusher.Pusher(
  app_id='YOUR_PUSHER_APP_ID',
  key='YOUR_PUSHER_KEY',
  secret='YOUR_PUSHER_SECRET',
  cluster='eu',
  ssl=True
)

# REST API örneği
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

# Son depremleri çek
response = requests.get(
    'https://your-domain.com/api/earthquakes',
    params={
        'min_mag': 3.0,
        'limit': 50,
        'since': '2025-01-01'
    },
    headers=headers
)

earthquakes = response.json()

for eq in earthquakes:
    print(f"{eq['magnitude']} M - {eq['place']} - {eq['occurred_at']}")

# Koordinat bazlı arama
response = requests.get(
    'https://your-domain.com/api/earthquakes',
    params={
        'near': '41.0082,28.9784',  # İstanbul koordinatları
        'radius_km': 50,
        'limit': 20
    },
    headers=headers
)

nearby_earthquakes = response.json()
print(f"İstanbul çevresinde {len(nearby_earthquakes)} deprem bulundu")

PHP

<?php
// composer require pusher/pusher-php-server guzzlehttp/guzzle

use Pusher\Pusher;
use GuzzleHttp\Client;

// REST API örneği
$client = new Client([
    'base_uri' => 'https://your-domain.com',
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN'
    ]
]);

$response = $client->get('/api/earthquakes', [
    'query' => [
        'min_mag' => 3.0,
        'limit' => 50,
        'since' => '2025-01-01'
    ]
]);

$earthquakes = json_decode($response->getBody(), true);

foreach ($earthquakes as $eq) {
    echo "{$eq['magnitude']} M - {$eq['place']} - {$eq['occurred_at']}\n";
}

// Koordinat bazlı arama
$response = $client->get('/api/earthquakes', [
    'query' => [
        'near' => '41.0082,28.9784',
        'radius_km' => 50,
        'limit' => 20
    ]
]);

$nearby = json_decode($response->getBody(), true);
?>

cURL

# Public endpoint
curl "https://your-domain.com/api/public/earthquakes?limit=20"

# Authenticated endpoint
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-domain.com/api/earthquakes?min_mag=3.0&limit=50"

# Koordinat bazlı arama
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-domain.com/api/earthquakes?near=41.0082,28.9784&radius_km=50"

🔗 Entegrasyon

İframe Entegrasyonu

Son depremler sayfasını kendi sitenize iframe ile entegre edebilirsiniz:

<iframe 
  src="https://your-domain.com/earthquakes" 
  width="100%" 
  height="600" 
  frameborder="0"
  style="border-radius:12px;"
  title="Son Depremler"
>
</iframe>

⚠️ Önemli: İframe kullanımında sayfanızda "Jaharia Community katkılarıyla" ibaresini eklemeniz gerekmektedir. Jaharia Community Discord →

Rate Limiting

API endpoint'leri rate limiting ile korunmaktadır. Aşırı istek yapmaktan kaçının.

CORS

WebSocket ve REST API endpoint'leri CORS desteği sağlar. Tarayıcı tabanlı uygulamalar için ek yapılandırma gerekmez.

🇹🇷 Jaharia Community Desteği

Bu sistem Jaharia community tarafından geliştirildi ve halka yararı olması için hedeflendi. Bu zorlu günlerde alınması gereken önlemleri almak için kanla başla çalışan vatandaşlar olduk. Bu yüzden bu sistem için topluluk desteğinizi bekliyoruz.

💬 Jaharia Community Discord'a Katıl

discord.gg/jahrein

🙏 Emeği Geçenler

anildev • Caine • Melih • EmirHosgeldin • Lacrima • w0fly

Veriler Boğaziçi Üniversitesi Kandilli Rasathanesi ve Deprem Araştırma Enstitüsü Bölgesel Deprem-Tsunami İzleme Ve Değerlendirme Merkezi'nden gelmektedir.

🌍 Türkiye Deprem API Dokümantasyonu

📋 İçindekiler

📖 Genel Bakış

Özellikler

Veri Kaynağı

🔐 Kimlik Doğrulama

API Anahtarı Alma

Token Kullanımı

📡 WebSocket API

Yetkilendirme Endpoint

İstek Parametreleri

Yetkilendirme Yöntemleri

Kullanılabilir Kanallar

Event: earthquake.detected

Event Payload Yapısı

Alanlar

🌐 REST API

1. Public Endpoint - Son Depremler

Query Parametreleri

Örnek İstek

Örnek Yanıt

2. Authenticated Endpoint - Gelişmiş Deprem Sorgulama

Query Parametreleri

Örnek İstekler

Yanıt Formatı

Hata Yanıtları

💻 Kod Örnekleri

JavaScript (Pusher Client)

Node.js

Python

PHP

cURL

🔗 Entegrasyon

İframe Entegrasyonu

Rate Limiting

CORS

🇹🇷 Jaharia Community Desteği

💬 Jaharia Community Discord'a Katıl

🙏 Emeği Geçenler