API Dokümantasyonu

⚡ Hızlı Başlangıç

Hesap oluşturun — kayıt formunu doldurun, email doğrulama linkine tıklayın.

Token üretin — Token'larım sayfasından yeni token oluşturun. Scope seçin: read / write / full.

İlk isteği gönderin:

curl -s https://api.oktasoft.com/api/v1/ping
# → {"pong": true}

curl -s https://api.oktasoft.com/api/v1/weather/current?city=Istanbul \
  -H "Authorization: Bearer okt_<token>"
# → {"city": "Istanbul", "temp_c": 18.3, ...}

🔑 Kimlik Doğrulama

Tüm /api/v1/* endpoint'leri (ping hariç) Bearer token gerektirir. Her istekte Authorization header'ı gönderilmelidir:

Authorization: Bearer okt_<tokeniniz>

Token'larınızı Token'larım sayfasından yönetin. Her hesaba birden fazla token ekleyebilirsiniz.

Base URL

https://api.oktasoft.com

Format

JSON (Content-Type: application/json)

Encoding

UTF-8

Swagger UI

/internal/docs

📊 Planlar & Limitler

Özellik	Free	Starter	Pro	Enterprise
Fiyat	0 ₺	99 ₺/ay	299 ₺/ay	Teklif
Günlük İstek	1,000	10,000	100,000	Sınırsız
/weather/current	✓	✓	✓	✓
/weather/forecast, /hourly, /historical	—	✓	✓	✓
/agri/field, /soil, /et0, /frost, /forecast	—	✓	✓	✓
/agri/irrigation, /gdd	—	—	✓	✓
/iot/* (tüm IoT endpoint'leri)	—	—	✓	✓

Planınızı yükseltmek için: /plan

🔒 Token Scope

Scope	Açıklama	Kullanım
read	Sadece GET endpoint'leri	Salt okunur dashboard, veri görüntüleme
write	POST + GET endpoint'leri	IoT cihazından sensör yazma (`/iot/write`)
full	Tüm endpoint'ler	Tam erişim gerektiğinde

⚠️ Hata Kodları

HTTP	error	Açıklama
200	—	Başarılı
401	unauthorized	Authorization header eksik
401	invalid_token	Token geçersiz veya devre dışı
403	plan_required	Bu endpoint için planınız yetersiz
403	insufficient_scope	Token scope'u yetki vermiyor
404	not_found	İstenen kayıt bulunamadı
422	invalid_data	Gönderilen veri geçersiz
429	rate_limit_exceeded	Günlük istek limitine ulaşıldı (gece 00:00 UTC sıfırlanır)
502	query_failed / write_failed	Upstream servis (InfluxDB / Open-Meteo) hatası

Örnek 403 yanıtı

{
  "error":         "plan_required",
  "message":       "Bu endpoint icin Starter veya uzeri plan gereklidir.",
  "your_plan":     "Free",
  "required_plan": "Starter",
  "upgrade_url":   "https://api.oktasoft.com/plan"
}

🌐 Genel Endpoint'ler

GET /api/v1/ping Token gerektirmez — servis sağlık kontrolü Herkese açık

Yanıt

{ "pong": true }

GET /api/v1/me Hesap ve token bilgisi Tüm planlar

Örnek Yanıt

{
  "user_id":    "3f7a1...",
  "plan":       "Pro",
  "token_id":   "8d2e4...",
  "scope":      "full"
}

GET /api/v1/usage Bugünkü istek kullanımı Tüm planlar

Örnek Yanıt

{
  "used":        47,
  "limit":       100000,
  "resets_at":   "midnight UTC",
  "plan":        "Pro"
}

⛅ Hava Durumu API

Veri kaynağı: Open-Meteo (ücretsiz, ek API anahtarı gerekmez). Şehir adı veya koordinat (lat/lon) ile sorgu yapılabilir.

GET /api/v1/weather/current Anlık hava durumu Free+

Query Parametreleri

Parametre	Zorunlu	Açıklama
city	city veya lat/lon	Şehir adı (ör. "Istanbul", "Ankara")
lat	city veya lat/lon	Enlem (ör. 39.92)
lon	city veya lat/lon	Boylam (ör. 32.85)

Örnek İstek

curl "https://api.oktasoft.com/api/v1/weather/current?city=Ankara" \
  -H "Authorization: Bearer okt_<token>"

Örnek Yanıt

{
  "city":          "Ankara",
  "lat":           39.9272,
  "lon":           32.8644,
  "temp_c":        11.8,
  "feels_like_c":  9.1,
  "humidity_pct":  72,
  "wind_speed_kmh":14.4,
  "pressure_hpa":  1018,
  "description":   "Parçalı Bulutlu",
  "is_day":        true
}

GET /api/v1/weather/forecast Günlük tahmin (max 16 gün) Starter+

Query Parametreleri

Parametre	Zorunlu	Varsayılan	Açıklama
city	city veya lat/lon	—	Şehir adı
lat	city veya lat/lon	—	Enlem
lon	city veya lat/lon	—	Boylam
days	Hayır	7	Tahmin günü sayısı (1–16)

Örnek Yanıt (kısaltılmış)

{
  "city": "Istanbul",
  "days": 7,
  "forecast": [
    {
      "date":          "2026-04-06",
      "temp_max_c":   18.5,
      "temp_min_c":   9.2,
      "precip_mm":    0.0,
      "wind_max_kmh": 22.1,
      "description":  "Açık"
    },
    ...
  ]
}

GET /api/v1/weather/hourly Saatlik veri (belirli bir tarih için) Starter+

Query Parametreleri

Parametre	Zorunlu	Varsayılan	Açıklama
city	city veya lat/lon	—	Şehir adı
lat / lon	city veya lat/lon	—	Koordinat
date	Hayır	Bugün	YYYY-MM-DD formatında tarih

Örnek Yanıt (kısaltılmış)

{
  "city": "Izmir",
  "date": "2026-04-06",
  "hours": [
    { "hour": "2026-04-06T00:00", "temp_c": 14.2, "humidity_pct": 81, "precip_mm": 0.0 },
    ... (24 kayıt)
  ]
}

GET /api/v1/weather/historical Geçmiş hava verisi Starter+

Query Parametreleri

Parametre	Zorunlu	Varsayılan	Açıklama
city / lat / lon	Evet	—	Konum
start_date	Hayır	7 gün önce	YYYY-MM-DD
end_date	Hayır	Dün	YYYY-MM-DD

Örnek Yanıt (kısaltılmış)

{
  "city":       "Konya",
  "start_date": "2026-03-30",
  "end_date":   "2026-04-05",
  "history":   [
    { "date": "2026-03-30", "temp_max_c": 16.1, "temp_min_c": 4.8, "precip_mm": 2.4 },
    ...
  ]
}

🌾 Tarım API (Agri)

Veri kaynakları: Open-Meteo (hava, toprak, ET₀ FAO-56 Penman-Monteith) + MQTT/IoT sensörler (varsa gerçek sensör verisini override eder).

GET /api/v1/agri/field Tarlaya özgü birleşik veri (hava + toprak + ET₀ + don + sulama) Starter+

Query Parametreleri

Parametre	Zorunlu	Açıklama
city / lat / lon	Evet	Tarla konumu

Örnek Yanıt

{
  "city":          "Konya",
  "air_temp_c":    14.3,
  "humidity_pct":  58,
  "soil_temp_c":   11.6,
  "soil_moisture": 0.27,
  "et0_mm":        3.09,
  "frost_risk":    "none",
  "irrigation_mm": 3.09
}

GET /api/v1/agri/soil Toprak sıcaklığı ve nem verisi Starter+

Query Parametreleri

Parametre	Zorunlu	Açıklama
city / lat / lon	Evet	Konum

Örnek Yanıt

{
  "city":              "Antalya",
  "soil_temp_0cm":    13.6,
  "soil_temp_6cm":    12.8,
  "soil_temp_18cm":   11.4,
  "soil_moisture":    0.279
}

GET /api/v1/agri/et0 Potansiyel evapotranspirasyon (FAO-56 Penman-Monteith) Starter+

Query Parametreleri

Parametre	Zorunlu	Varsayılan	Açıklama
city / lat / lon	Evet	—	Konum
days	Hayır	7	Gün sayısı (1–16)

Örnek Yanıt

{
  "city":       "Ankara",
  "days":       5,
  "total_et0_mm": 13.63,
  "daily": [
    { "date": "2026-04-06", "et0_mm": 2.84 },
    ...
  ]
}

GET /api/v1/agri/frost 7 günlük don riski tahmini ve uyarıları Starter+

Risk Seviyeleri

Seviye	Min Sıcaklık	Açıklama
critical	≤ 0°C	Don oluşumu, acil önlem gerekli
high	≤ 2°C	Yüksek don riski
medium	≤ 4°C	Orta risk, izle
low	≤ 6°C	Düşük risk
none	> 6°C	Don riski yok

Örnek Yanıt

{
  "city": "Erzurum",
  "alert": "⚠️ Don uyarısı: 2026-04-06 − critical (−0.5°C)",
  "forecast": [
    { "date": "2026-04-06", "min_temp_c": -0.5, "frost_risk": "critical" },
    ...
  ]
}

GET /api/v1/agri/irrigation Günlük sulama tavsiyesi (ET₀ − yağış) Pro+

Query Parametreleri

Parametre	Zorunlu	Varsayılan	Açıklama
city / lat / lon	Evet	—	Konum
days	Hayır	7	Gün sayısı

Aciliyet Seviyeleri

Aciliyet	Net Su İhtiyacı
none	≤ 0 mm (yağmur yeterliydi)
low	0–2 mm
medium	2–5 mm
high	> 5 mm

Örnek Yanıt

{
  "city":          "Konya",
  "total_net_mm":  15.4,
  "daily": [
    {
      "date":        "2026-04-06",
      "et0_mm":     3.1,
      "precip_mm":  0.0,
      "net_mm":     3.1,
      "urgency":    "medium"
    },
    ...
  ]
}

GET /api/v1/agri/gdd Büyüme gün derecesi (Growing Degree Day) Pro+

Query Parametreleri

Parametre	Zorunlu	Varsayılan	Açıklama
city / lat / lon	Evet	—	Konum
days	Hayır	7	Gün sayısı
base_temp	Hayır	10.0	Baz sıcaklık °C (buğday=0, mısır=10)

GDD Formülü

# GDD = max(0, (T_max + T_min) / 2 − T_base)

Örnek Yanıt

{
  "city":           "Adana",
  "base_temp":      10.0,
  "cumulative_gdd": 42.7,
  "daily": [
    { "date": "2026-04-06", "gdd": 6.35, "cumulative": 6.35 },
    ...
  ]
}

GET /api/v1/agri/forecast 7 günlük kapsamlı tarımsal tahmin Starter+

Query Parametreleri

Parametre	Zorunlu	Açıklama
city / lat / lon	Evet	Konum

Örnek Yanıt

{
  "city": "Izmir",
  "forecast": [
    {
      "date":        "2026-04-06",
      "temp_max_c":  22.1,
      "temp_min_c":  11.3,
      "precip_mm":   0.0,
      "et0_mm":      4.2,
      "frost_risk":  "none",
      "gdd":         6.7,
      "irr_net_mm": 4.2,
      "irr_urgency":"medium"
    },
    ...
  ]
}

📡 IoT Data API

Veri depolama: InfluxDB 2. Çok-kiracılı izolasyon: her yazma/sorgu user_id etiketi ile filtrelenir — diğer kullanıcıların verisi görünmez. Tüm endpoint'ler Pro+ plan gerektirir.

POST /api/v1/iot/write Sensör verisini InfluxDB'ye yazar Pro+ · write/full scope

Request Body (JSON)

Alan	Tür	Zorunlu	Açıklama
device_id	string	Evet	Cihaz kimliği (ör. "TR-FLD-001"), max 100 karakter
measurements	object	Evet	Alan→değer sözlüğü (sayısal değerler)
timestamp	string	Hayır	ISO 8601 (ör. "2026-04-06T14:00:00Z"), boşsa sunucu zamanı

Desteklenen Alanlar

Alan	Birim	Açıklama
soil_temp	°C	Toprak sıcaklığı (0 cm)
soil_temp_6cm	°C	Toprak sıcaklığı (6 cm)
soil_temp_18cm	°C	Toprak sıcaklığı (18 cm)
soil_moisture	m³/m³	Toprak nemi (hacimsel)
air_temp	°C	Hava sıcaklığı
humidity	%	Bağıl nem
dew_point	°C	Çiğ noktası
pressure_hpa	hPa	Atmosfer basıncı
wind_speed_ms	m/s	Rüzgar hızı
rainfall_mm	mm	Yağış miktarı
uv_index	—	UV indeksi
light_lux	lux	Işık yoğunluğu
co2_ppm	ppm	CO₂ konsantrasyonu
battery_pct	%	Batarya yüzdesi
rssi	dBm	Sinyal gücü

Örnek İstek

curl -X POST "https://api.oktasoft.com/api/v1/iot/write" \
  -H "Authorization: Bearer okt_<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "TR-FLD-001",
    "measurements": {
      "soil_temp":     16.2,
      "soil_moisture": 0.28,
      "air_temp":      18.5,
      "humidity":      55.0,
      "battery_pct":   87.0
    },
    "timestamp": "2026-04-06T14:00:00Z"
  }'

Örnek Yanıt

{
  "written":      true,
  "device_id":    "TR-FLD-001",
  "fields":       ["soil_temp", "soil_moisture", "air_temp", "humidity", "battery_pct"],
  "field_count":  5,
  "timestamp":    "2026-04-06T14:00:00+00:00"
}

GET /api/v1/iot/query InfluxDB'den sensör verisi sorgular Pro+

Query Parametreleri

Parametre	Varsayılan	Açıklama
device_id	—	Cihaz ID filtresi (boşsa tüm cihazlar)
start	-24h	Başlangıç: `-24h`, `-7d`, `2026-04-01T00:00:00Z`
end	now()	Bitiş: `now()` veya ISO tarih
window	—	Gruplama aralığı: `5m`, `1h`, `1d` (ortalama alır)
fields	—	Virgülle ayrılmış alan listesi: `soil_temp,humidity`

Örnek İstek

curl "https://api.oktasoft.com/api/v1/iot/query?device_id=TR-FLD-001&start=-7d&window=1h" \
  -H "Authorization: Bearer okt_<token>"

Örnek Yanıt

{
  "device_id": "TR-FLD-001",
  "start":     "-7d",
  "end":       "now()",
  "window":    "1h",
  "count":     168,
  "records": [
    { "time": "2026-04-06T00:00:00+00:00", "device_id": "TR-FLD-001", "soil_temp": 14.1, "air_temp": 9.8 },
    ...
  ]
}

GET /api/v1/iot/devices Hesaba kayıtlı cihazları listeler Pro+

Örnek Yanıt

{
  "count": 2,
  "devices": [
    {
      "device_id":  "TR-FLD-001",
      "name":       null,
      "last_seen":  "2026-04-06T14:00:00+00:00",
      "registered": "2026-04-05T09:12:00+00:00"
    },
    ...
  ]
}

GET /api/v1/iot/devices/{device_id}/last Cihazın en son ölçümü (son 30 gün) Pro+

Path Parametresi

Parametre	Açıklama
device_id	Cihaz kimliği (ör. TR-FLD-001)

Örnek İstek

curl "https://api.oktasoft.com/api/v1/iot/devices/TR-FLD-001/last" \
  -H "Authorization: Bearer okt_<token>"

Örnek Yanıt

{
  "time":          "2026-04-06T14:00:00+00:00",
  "device_id":     "TR-FLD-001",
  "soil_temp":     16.8,
  "soil_moisture": 0.27,
  "air_temp":      19.1,
  "humidity":      53.0,
  "battery_pct":   86.0
}

GET /api/v1/iot/devices/{device_id}/summary Son 24 saat min/mean/max istatistikler Pro+

Örnek İstek

curl "https://api.oktasoft.com/api/v1/iot/devices/TR-FLD-001/summary" \
  -H "Authorization: Bearer okt_<token>"

Örnek Yanıt

{
  "device_id": "TR-FLD-001",
  "period":    "last_24h",
  "stats": {
    "soil_temp":     { "min": 14.1, "mean": 15.9, "max": 17.3 },
    "soil_moisture": { "min": 0.24, "mean": 0.27, "max": 0.31 },
    "air_temp":      { "min": 9.8,  "mean": 14.6, "max": 19.1 },
    "battery_pct":   { "min": 85.0, "mean": 86.2, "max": 87.0 }
  }
}