Derece Gün API'si

Derece günler#

Parametreler

{
  "location": {
    "latitude": 36.75, "longitude": 3.06,
    "grid_cell": { "latitude": 36.7, "longitude": 3.1,
                   "distance_km": 6.61, "resolution_km": 9 }
  },
  "parameters": {
    "base_temperature_c": 18.0, "method": "hourly",
    "start": "2025-07-01", "end": "2026-06-30"
  },
  "totals": { "hdd": 781.86, "cdd": 1331.61 },
  "quality": {
    "days": 365, "coverage": 1.0,
    "missing_hours": 0, "provisional_days": 0
  },
  "breakdown": [ { "year": 2025, "month": 7, "hdd": 0.0, "cdd": 289.4, "days": 31 } ]
}

Derece gün nedir, tek paragrafta

Bir ısıtma derece günü, dış havanın bir taban sıcaklığının ne kadar altında ve ne kadar süre kaldığını ölçer. 18 °C tabanında, 16 °C'de geçen bir saat (18 − 16) / 24 = 0.083 HDD katkı verir. Saatleri toplayın ve elinizde bir binanın ihtiyaç duyduğu enerjiyle orantılı bir sayı olsun. Soğutma derece günleri bunun aynasıdır: tabanın ne kadar üstünde. Havanın karşılaştırmadan çıkarılmasının ardından bir ısıtma sezonunu bir diğeriyle karşılaştırmanın standart yolu budur.

Çok taban, tek istek, tek fiyat#

Saatlik seriyi okumak ve çözmek, bir derece gün yanıtının bütün maliyetidir. O dizi bir kez bellekteyken başka bir taban, üzerinde bir çıkarma işlemidir; yani altmış taban istemek bir taban istemekle aynı maliyettedir.

Yanıt, listelediğiniz sırayla bütün tabanları taşıyan bir by_base dizisi kazanır. totals ve breakdown ilkini betimlemeyi sürdürür; böylece bu özellik var olmadan önce yazılmış kod değişmeden çalışır.

"by_base": [
  {"base": 15.0,  "hdd": 402.11, "cdd": 1731.4},
  {"base": 15.5,  "hdd": 431.02, "cdd": 1706.3},
  {"base": 18.0,  "hdd": 781.86, "cdd": 1331.6}
]

Bir sözleşmenin rakamlarını hangi tabanın yeniden ürettiğini henüz bilmediğinizde ya da aynı bina farklı taraflarca farklı tabanlarda kapatıldığında işe yarar — 15,5 kullanan bir mal sahibi ile 18 kullanan bir enerji tedarikçisi ikisi de haklıdır ve bu, ikisini tek çağrıda döndürür.

Hesaplama yöntemleri#

Yöntem bir parametredir, çünkü ona biz değil, sözleşmeniz karar verir. Aynı veri, aynı taban, aynı yıl, Cezayir'de:

eurostat, base değerini tümüyle yok sayar: tanım kendi eşiklerini sabitler ve parametrenize uymak, Eurostat derece günü olmadığı hâlde öyleymiş gibi görünen bir sayı üretirdi.

/v1/methods anahtar gerektirmez. Arayüzünüzdeki bir yöntem seçicisini hiçbir şey harcamadan ve bayatlayacak bir listeyi koda gömmeden doldurmak için kullanın.

Şehre göre derece günler#

Çıplak bir koordinatın yapamayacağı iki düzeltmeyi uygular: günlerin yerel olarak kesilmesi için şehrin saat dilimi ve şehrin kalibre edilmiş kentsel ısı adası kayması.

Yeniden analiz, yapılaşmış alanları 1–3 °C düşük okur. Bu, soğutma derece günlerini olduğundan düşük gösterir — klima boyutlandırıyorsanız önemli, aramanız gerektiğini bilmiyorsanız görünmezdir.

Izgara hücresi için değil, binanız için derece günler#

Bir meteoroloji istasyonu bulunduğu yükseklikte durur ve kimse onu sizin için vadi yamacında 600 m yukarı taşıyamaz. Bizim kaynağımız bir model olduğundan hücrenin zemin yüksekliği arşivde bir sayıdır ve fark aritmetiktir: her 100 m için 0,65 °C. Bir ısıtma sezonu boyunca bu bir yuvarlama hatası değildir.

İsteğe bağlıdır ve yanıt tam olarak ne yaptığını söyler:

"elevation": {
  "applied": true,
  "model_elevation_m": 42.0,
  "location_elevation_m": 1200,
  "temperature_offset_c": -7.53,
  "caveat": "Lapse-rate correction. It assumes temperature falls smoothly with
             height, which a valley floor under a winter inversion does not."
}

Uyarı yalnızca bu sayfada değil, yanıtın içinde yolculuk eder; çünkü bu JSON'u altı ay sonra okuyacak kişi, belgeleri okumuş olan kişi değildir.

Bir referans karşılaştırılabilir kalsın diye hücreyi sabitlemek#

Diğer bütün konum biçimleri her istekte en yakın hücre aramasını yeniden çalıştırır; yani yanıt, arşivin bugün ne tuttuğuna bağlıdır. Tek seferlik bir sorgu için doğru varsayılan budur, bir referans için ise yanlış: çok yıllı bir karşılaştırma, ancak her yıl aynı yerden geliyorsa karşılaştırmadır.

Arşiv genişledikçe belirli bir sahaya en yakın hücre değişir — verinize başka türlü açıklanamayan bir basamak olarak ulaşacak bir kapsama iyileşmesi.

# bir kez, kurulumda
GET /v1/cells/resolve?lat=45.19&lon=5.72
  → { "id": "era5l_45.20_5.70", "distance_km": 1.4, "resolution_km": 9 }

# ondan sonra her seferinde
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

Sabitlenmiş bir istekte distance_km yapısı gereği 0'dır: hücreyi siz adlandırdınız, dolayısıyla yerine hiçbir şey konmadı. Artık var olmayan bir hücre, sessizce bir komşuya düşmek yerine 404 cell_not_found döndürür — komşuya düşmek, sabitleyerek kaçındığınız o yerine koymayı geri getirirdi.

Ayrıntı dönemleri#

Her derece gün yanıtı, istediğiniz döneme toplulaştırılmış bir breakdown dizisi taşır. Sözleşmeler farklı dönemler üzerinden kapanır; bu yüzden dördü de aynı istekte, aynı fiyata sunulur.

Her kova ayrıca days taşır; böylece aralığınızın kenarındaki eksik bir ay sessizce kısa kalmak yerine görünür olur. "days": 12 olan bir şubat, tam bir şubatla karşılaştırmamanız gereken bir şubattır.

Bir yılın aylık toplamları#

Yaygın durum için bir kısayol: ?lat=&lon=&year=2025 ve on iki satır döner. Aynı aralıkta /v1/degree-days?breakdown=monthly ile aynı veri; yanlış yazılacak daha az parametre.

/v1/coverage arşivin ilk ve son gününü ve çözünürlüğünü bildirir, anahtar gerektirmez ve şimdiki zamanın kenarına yakın bir dönem istemeden önce bakılacak doğru yerdir — ERA5-Land yaklaşık beş gün geriden gelir ve yanıtınızdaki provisional_days bunun sonucudur.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // veri TUTAN son gün
  "axis_end": "2026-12-31",   // bu koşunun büyümeyi bırakacağı yer
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

CSV dışa aktarma#

Herhangi bir derece gün isteğine format=csv ekleyin. breakdown satırlarını bir CSV dosyası olarak alırsınız; dosya adı konum ve tarihlerden türetilir, böylece altı ay sonra indirilenler klasöründe hâlâ tanınabilir olur.

year,month,hdd,cdd,days,t_mean,coverage,provisional
2024,1,205.03,2.88,31,11.48,1.0,false
2024,2,168.44,4.10,29,12.31,1.0,false

Yalnızca ücretli planlar ve sınırlı: JSON isteğiyle aynı en büyük aralık, yalnızca toplulaştırılmış satırlar — saatlik seri asla — ve eşdeğer JSON çağrısının her bir kredisine karşılık dört kredi. Ücretsiz bir anahtar 402 export_not_in_plan alır.

Bu, gönülsüzlükten değil, bilinçli bir tercihtir. Ödediğiniz şey arşivdir ve sınırsız bir dışa aktarma, bir rakibin onu bir öğleden sonrada edinme yoludur. Bu formatın var olabilmesini sağlayan şey, o sınırlardır.

Saatlik geçmiş#

Parametreler

Derece günlerin üzerine kurulduğu arşivin doğrudan sunulmuş hâli: saatlik, 1950'ye kadar geriye, 9 km'lik ızgarada, karada her yerde. Aynı sunucu ve aynı dju scope'u — derece günleri çağırabiliyorsanız bunu da çağırabilirsiniz.

Uzun bir dönemdeki günlük değerler ya da normaller ve eğilimler için bunun yerine İklim API'sini kullanın — günlük alanları önceden türetilmiş hâlde tutar, 9 km/1950 sınırı yoktur ve bütün bir iklimolojiyi tek çağrıda yanıtlar.

Şehre göre geçmiş#

Bir koordinatın taşıyamayacağı iki şey: günlerin şehrin onları gerçekten yaşadığı yerde kesilmesi için şehrin saat dilimi ve şehrin kalibre edilmiş kentsel ısı adası düzeltmesi. Burada daily varsayılan olarak doğrudur; çünkü bir şehir isteği neredeyse her zaman günlerle ilgili bir istektir.

Kullanılabilir değişkenler#

Arşivin şu anda neyi tuttuğunu birimleriyle birlikte ve hangi alanların saklanmak yerine türetildiğini listeler. Yalnızca derece günler için alınmış bir arşiv sadece sıcaklık tutar ve bu uç nokta, null sütunları döndürmek yerine bunu açıkça söyler.