API Derajat-Hari

Derajat-hari#

Parameter

{
  "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 } ]
}

Apa itu derajat-hari, dalam satu paragraf

Satu derajat-hari pemanasan mengukur seberapa jauh udara luar berada di bawah suhu basis, dan selama berapa lama. Pada basis 18 °C, satu jam pada 16 °C menyumbang (18 − 16) / 24 = 0.083 HDD. Jumlahkan jam-jamnya dan Anda mendapat angka yang sebanding dengan energi yang dibutuhkan sebuah bangunan. Derajat-hari pendinginan adalah cerminannya: seberapa jauh di atas basis. Inilah cara baku membandingkan satu musim pemanasan dengan musim lainnya setelah faktor cuaca dikeluarkan dari perbandingan.

Banyak basis, satu permintaan, satu harga#

Membaca dan mendekode deret per jam adalah seluruh biaya sebuah jawaban derajat-hari. Begitu larik itu ada di memori, basis tambahan hanyalah pengurangan di atasnya, jadi meminta enam puluh basis berbiaya sama dengan meminta satu.

Respons mendapat tambahan larik by_base yang membawa semua basis sesuai urutan yang Anda sebutkan. totals dan breakdown tetap menggambarkan basis pertama, sehingga kode yang ditulis sebelum fitur ini ada tetap berjalan tanpa perubahan.

"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}
]

Berguna ketika Anda belum tahu basis mana yang mereproduksi angka sebuah kontrak, atau ketika bangunan yang sama diselesaikan pada basis berbeda oleh pihak berbeda — pemilik gedung memakai 15,5 dan pemasok energi memakai 18, keduanya benar, dan ini mengembalikan keduanya dalam satu panggilan.

Metode perhitungan#

Metode dijadikan parameter karena kontrak Andalah yang menentukannya, bukan kami. Data sama, basis sama, tahun sama, di Aljir:

eurostat mengabaikan base sepenuhnya: definisinya menetapkan ambangnya sendiri, dan menuruti parameter Anda akan menghasilkan angka yang bukan derajat-hari Eurostat padahal mengaku demikian.

/v1/methods tidak butuh kunci. Pakai untuk mengisi pemilih metode di antarmuka Anda tanpa mengeluarkan biaya apa pun, dan tanpa menanam daftar yang akan basi.

Derajat-hari per kota#

Menerapkan dua koreksi yang tidak bisa dilakukan koordinat telanjang: zona waktu kota, agar hari dipotong secara lokal, dan offset pulau bahang perkotaan yang sudah dikalibrasi.

Reanalisis membaca kawasan terbangun terlalu rendah sebesar 1–3 °C. Itu membuat derajat-hari pendinginan bias ke bawah — berarti besar jika Anda sedang menghitung kapasitas pendingin udara, dan tak terlihat jika Anda tidak tahu harus mencarinya.

Derajat-hari untuk bangunan Anda, bukan untuk sel grid#

Sebuah stasiun cuaca berada pada ketinggian tempatnya berdiri, dan tak seorang pun bisa memindahkannya 600 m ke atas lereng lembah demi Anda. Sumber kami adalah model, jadi ketinggian tanah sel itu adalah sebuah angka di dalam arsip dan selisihnya tinggal aritmetika: 0,65 °C per 100 m. Sepanjang satu musim pemanasan, itu bukan galat pembulatan.

Bersifat opsional, dan responsnya menyebutkan persis apa yang dilakukan:

"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."
}

Peringatannya ikut di dalam respons, bukan hanya di halaman ini, karena orang yang membaca JSON itu enam bulan lagi bukanlah orang yang membaca dokumentasinya.

Menyematkan sel, agar sebuah baseline tetap bisa dibandingkan#

Semua bentuk lokasi lain menjalankan ulang pencarian sel terdekat pada setiap permintaan, jadi jawabannya bergantung pada isi arsip hari ini. Itu perilaku bawaan yang tepat untuk pencarian sekali jalan, dan keliru untuk sebuah baseline: perbandingan lintas tahun baru menjadi perbandingan jika setiap tahun berasal dari tempat yang sama.

Seiring meluasnya arsip, sel terdekat dari sebuah lokasi bisa berubah — perbaikan cakupan yang jika tidak disematkan akan masuk ke data Anda sebagai lompatan tanpa penjelasan.

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

# setiap kali sesudahnya
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km bernilai 0 pada permintaan tersemat sejak awal: Anda menyebut selnya, jadi tidak ada yang digantikan. Sel yang sudah tidak ada mengembalikan 404 cell_not_found alih-alih diam-diam jatuh ke sel tetangga — yang justru akan menghadirkan kembali penggantian yang ingin Anda hindari dengan menyematkannya.

Periode rincian#

Setiap respons derajat-hari membawa larik breakdown yang diagregasi ke periode yang Anda minta. Kontrak diselesaikan pada periode yang berbeda-beda, jadi keempatnya tersedia pada permintaan yang sama dengan harga yang sama.

Setiap keranjang juga membawa days, sehingga bulan yang tidak utuh di tepi rentang Anda terlihat alih-alih diam-diam lebih pendek. Bulan Februari dengan "days": 12 adalah Februari yang tidak boleh Anda bandingkan dengan Februari yang utuh.

Total bulanan untuk satu tahun#

Jalan pintas untuk kasus umum: ?lat=&lon=&year=2025 dan dua belas baris kembali. Data yang sama dengan /v1/degree-days?breakdown=monthly pada rentang yang sama; lebih sedikit parameter yang bisa salah.

/v1/coverage melaporkan hari pertama dan terakhir arsip beserta resolusinya, tidak butuh kunci, dan merupakan hal yang tepat diperiksa sebelum Anda meminta periode dekat batas kekinian — ERA5-Land tertinggal sekitar lima hari, dan provisional_days di respons Anda adalah konsekuensinya.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // hari terakhir yang MEMUAT data
  "axis_end": "2026-12-31",   // tempat run ini akan berhenti tumbuh
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

Ekspor CSV#

Tambahkan format=csv ke permintaan derajat-hari mana pun. Anda mendapat baris breakdown sebagai berkas CSV, dinamai menurut lokasi dan tanggalnya sehingga enam bulan kemudian masih bisa dikenali di folder unduhan.

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

Hanya paket berbayar, dan dibatasi: rentang maksimum yang sama dengan permintaan JSON, hanya baris teragregasi — tidak pernah deret per jam — dan biayanya empat kredit untuk setiap satu kredit yang dikenakan panggilan JSON setara. Kunci gratis mendapat 402 export_not_in_plan.

Itu disengaja, bukan setengah hati. Arsip inilah yang Anda bayar, dan ekspor tanpa batas adalah cara pesaing memilikinya dalam satu sore. Batas-batas itulah yang membuat format ini bisa ada sama sekali.

Riwayat per jam#

Parameter

Arsip yang sama yang menjadi dasar derajat-hari, dilayani langsung: per jam, mundur sampai 1950, pada grid 9 km, di seluruh daratan. Host yang sama dan scope dju yang sama — jika Anda bisa memanggil derajat-hari, Anda bisa memanggil ini.

Untuk nilai harian sepanjang periode panjang, atau untuk normal dan tren, gunakan API Iklim — ia menyimpan field harian yang sudah diturunkan, tidak punya batas 9 km/1950, dan menjawab satu klimatologi utuh dalam satu panggilan.

Riwayat per kota#

Dua hal yang tidak bisa dibawa koordinat: zona waktu kota, agar hari dipotong sesuai yang benar-benar dialami kota itu, dan koreksi pulau bahang perkotaannya yang sudah dikalibrasi. Di sini daily bernilai true secara bawaan, karena permintaan per kota hampir selalu merupakan permintaan tentang hari.

Variabel yang tersedia#

Menampilkan apa yang dimuat arsip saat ini, lengkap dengan satuannya, dan field mana yang diturunkan alih-alih disimpan. Arsip yang dicerna hanya untuk derajat-hari hanya memuat suhu, dan endpoint ini mengatakannya terang-terangan alih-alih mengembalikan kolom berisi null.