API Cuaca

Prakiraan#

Parameter

Respons

{
  "latitude": 48.85,
  "longitude": 2.35,
  "timezone": "Europe/Paris",
  "grid": {
    "latitude": 48.85, "longitude": 2.35,
    "distance_km": 0.42, "resolution_km": 1.3
  },
  "elevation": {
    "applied": true,
    "model_elevation_m": 91.0,
    "location_elevation_m": 113,
    "temperature_offset_c": -0.14
  },
  "source": {
    "model": "mf_arome",
    "model_run": "20260801T00Z",
    "reference_time": "2026-08-01T00:00:00+00:00",
    "data_age_hours": 3.95,
    "stale": false,
    "attribution": "Data: Météo-France (etalab-2.0)"
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+02:00", "..."],
    "temperature_2m": [18.1, 17.9, 17.6, "..."],
    "apparent_temperature": [17.4, "..."],
    "weather_code": [0, 1, 2, "..."]
  },
  "daily": {
    "date": ["2026-08-01", "..."],
    "temperature_2m_max": [26.6, "..."],
    "temperature_2m_min": [16.2, "..."],
    "precipitation_sum": [0.0, "..."],
    "uv_index_max": [7.6, "..."],
    "sunrise": ["2026-08-01T06:24:00+02:00", "..."],
    "sunset": ["2026-08-01T21:24:00+02:00", "..."],
    "daylight_hours": [15.0, "..."]
  }
}

Memperkecil muatan

Blok per jam yang lengkap untuk 15 hari kira-kira 32 field × 360 jam. Jika Anda hanya menggambar tiga di antaranya, mintalah tiga:

GET /v1/forecast?lat=48.85&lon=2.35&days=3
    &hourly=temperature_2m,precipitation,weather_code
    &include_daily=false

Harganya sama — biayanya ada pada pembacaan arsip, bukan penyerialan — tetapi byte-nya sepersepuluh dan terasa lebih cepat diurai di ponsel.

Prakiraan per kota#

Pilih ini ketimbang koordinat mentah bila memungkinkan. Katalog menyediakan dua hal yang tidak bisa diberikan koordinat: ketinggian sebenarnya kota itu, sehingga koreksi medan berjalan tanpa Anda memasoknya, dan zona waktunya, sehingga agregat harian dipotong pada hari lokal yang benar.

GET /v1/forecast/city/dz/alger      # slug Prancis
GET /v1/forecast/city/dz/algiers    # slug Inggris — kota yang sama
GET /v1/forecast/city/fr/paris

country adalah kode ISO-3166-1 alpha-2 dalam huruf kecil. slug mengabaikan tanda diakritik: bejaia menemukan Béjaïa. Slug yang tidak dikenal mengembalikan 404 city_not_found beserta larik suggestions — tampilkan itu alih-alih jalan buntu.

Semua parameter kueri /v1/forecast tetap berlaku kecuali lat, lon, dan elevation, yang disediakan katalog. Mengirim timezone menimpa zona milik kota itu, yang hampir tidak pernah Anda inginkan.

Kondisi terkini#

Suhu, kelembapan, angin, dan tekanan diinterpolasi linear ke saat ini, di antara dua langkah model yang mengapitnya.

Gunakan ini untuk tampilan "saat ini". Untuk apa pun yang akan Anda bandingkan lintas waktu, pakai /v1/forecast lalu baca jam yang Anda inginkan: deretnya stabil, sedangkan sekarang bergeser di bawah Anda di antara dua panggilan.

Referensi field#

Field per jam

21 di antaranya kembali secara bawaan. Sisanya milik Anda jika diminta — sebutkan di hourly=, dipisah koma — dan ditahan karena biaya, bukan karena ragu: setiap field tersimpan adalah pembacaan terkompresi tersendiri, jadi respons bawaan yang membawa seluruh 45 field akan membuat semua orang membayar demi segelintir yang menginginkan ketebalan salju.

GET /v1/forecast?lat=45.19&lon=5.72&hourly=temperature_2m,snow_line_altitude,soil_temperature_8cm

Field yang tidak diterbitkan sebuah model kembali sebagai null pada bagian prakiraan milik model itu, alih-alih lenyap dari respons — sehingga rantai yang dimulai di AROME dan berlanjut di ICON-EU tetap mengembalikan visibility sepanjang deret, kosong pada 51 jam pertama. Nama field yang tidak dikenal menghasilkan 400 unknown_field, dengan saran kecocokan terdekat; dulu ia diabaikan diam-diam.

Field harian

date, temperature_2m_max, temperature_2m_min, temperature_2m_mean, precipitation_sum, wind_speed_max, wind_gust_max, shortwave_radiation_sum (MJ/m²), uv_index_max, sunrise, sunset, daylight_hours, weather_code.

Diagregasi pada hari kalender lokal, bukan UTC. Hari yang tidak utuh di salah satu ujung rentang dihilangkan alih-alih dilaporkan dengan maksimum yang menyesatkan — jadi permintaan 7 hari sah saja mengembalikan 6 baris harian.

Model dan resolusi#

Kami melayani model terhalus yang mencakup titik Anda dan tenggat Anda. Anda tidak pernah memilihnya; pilihannya dilaporkan di source.model sehingga Anda selalu tahu mana yang menjawab.

Model beresolusi tinggi semuanya berjangkau pendek — pada 1 km atmosfer menjadi kacau dalam dua hari, sehingga memprakirakan lebih jauh tidak bermakna — karena itu resolusinya menurun bertahap seiring majunya prakiraan:

hari 0 ────── hari 2 ────── hari 5 ─────────────── hari 15
  AROME 1,3 km (Prancis)
  ICON-D2 2,2 km (Jerman, Alpen, Benelux)
  HRRR 3 km (AS dan Kanada selatan)
              ICON-EU 6,5 km (Eropa)
                          ICON 13 km · ECMWF 28 km (global)
                                              AIFS (hanya tren)

Peralihan di tepi domain sebuah model disilangsamarkan, sehingga dua kota di kedua sisi batas tidak pernah berbeda secara melompat.

/v1/models tidak butuh kunci, sehingga cocok untuk dipanggil dari halaman status atau diperiksa sebelum Anda membeli: ia melaporkan run terbaru setiap model beserta usianya, jadi "apakah datanya segar" bisa dijawab tanpa menghabiskan satu kredit pun.

Probabilitas ensemble#

Satu prakiraan tunggal berkata 22 °C pada hari Kamis. Itu tebakan yang disajikan sebagai fakta. Endpoint ini menjawab pertanyaan yang sebenarnya Anda pakai untuk memutuskan: seberapa yakin, dan berapa peluang hujan yang layak diperhitungkan.

Ia dihitung dari ensemble ECMWF — model yang sama dijalankan 50 kali dari kondisi awal yang sedikit berbeda. Di tempat run-run itu sepakat, prakiraannya yakin. Di tempat mereka menyebar, atmosfernya sendirilah yang tidak pasti, dan tidak ada model, sebaik apa pun, yang bisa memberi tahu lebih banyak.

{
  "members": 50,
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "temperature_2m_p10": [26.4],
    "temperature_2m_p50": [26.78],
    "temperature_2m_p90": [27.3],
    "temperature_2m_spread": [0.4],
    "precipitation_probability_0_1mm": [10.0],
    "precipitation_probability_1_0mm": [0.0],
    "precipitation_probability_5_0mm": [0.0],
    "precipitation_probability_10_0mm": [0.0],
    "precipitation_p90": [0.1]
  }
}

Cara membacanya

p10 dan p90 mengapit 80 % anggota di tengah: satu dari sepuluh memperkirakan lebih dingin daripada p10, satu dari sepuluh lebih hangat daripada p90. spread sebesar 0,4 °C berarti situasi mapan yang bisa Anda percaya; 3 °C berarti model-model berbeda pendapat dan Anda sebaiknya mengatakan itu kepada pengguna alih-alih memilih salah satu.

Ambang hujan adalah keputusan, bukan angka bulat — 0,1 mm berarti basah sama sekali, 1 mm berarti bawa jaket, 5 dan 10 mm berarti ini masalah. precipitation_p90 adalah kasus buruknya: hanya satu anggota dari sepuluh yang lebih basah.

Kualitas udara#

Inilah endpoint yang paling penting di Afrika Utara dan kawasan Mediterania. Satu episode debu mendorong PM10 melewati seribu mikrogram per meter kubik selama berhari-hari, yang merupakan keputusan kesehatan alih-alih sekadar angka, dan cakupannya buruk pada layanan konsumen gratis.

{
  "current": {
    "pm2_5": 38.7,
    "band": "poor",
    "who_guidelines_ug_m3": {"pm2_5": 15.0, "pm10": 45.0,
                             "nitrogen_dioxide": 25.0, "ozone": 100.0}
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "pm2_5": [38.7], "pm10": [85.8], "ozone": [43.4],
    "nitrogen_dioxide": [19.0], "dust_aod_550nm": [0.24]
  },
  "units": {"pm2_5": "ug/m3", "pm10": "ug/m3", "dust_aod_550nm": "1"}
}

Semua konsentrasi dinyatakan dalam µg/m³, satuan yang dipakai di mana-mana untuk kualitas udara. dust_aod_550nm adalah kedalaman optis dan tidak bersatuan: di atas sekitar 0,5 langit tampak berkabut, di atas 1,0 matahari meredup.

Nilai panduan jangka pendek WHO ikut serta di setiap respons agar sebuah angka bisa ditempatkan tanpa perlu dicari. band mengikuti indeks kualitas udara Eropa untuk PM2,5: baik, cukup, sedang, buruk, sangat buruk, amat sangat buruk.

Salju dan batas salju#

Empat field, dan masing-masing menjawab pertanyaan berbeda. snowfall adalah berapa banyak yang turun; sisanya menggambarkan apa yang menumpuk di tanah dan di mana.

Mintalah dengan menyebut namanya — semuanya tidak ada di respons bawaan:

GET /v1/forecast?lat=45.19&lon=5.72&hourly=snowfall,snow_depth,snow_water_equivalent,snow_line_altitude,freezing_level_altitude

Batas saljulah yang layak dibaca. "Di 800 m hujan dan di 1200 m salju" adalah keputusan yang bisa ditindaklanjuti resor ski, otoritas jalan, atau pengemudi; "3 mm presipitasi" bukan. Ini juga penting di Afrika Utara — Pegunungan Atlas punya area ski di Chréa dan Tikjda, dan dataran tinggi di Sétif, Batna, serta Djelfa berada di atas 1000 m.

Data ini berasal dari ICON milik DWD, yang mencakup dunia pada 13 km. Data terbuka ECMWF menerbitkan ketebalan salju tetapi tidak batas salju, jadi ini salah satu tempat model yang lebih kasar justru lebih berguna. snow_line_altitude adalah produk regional: ICON-EU dan ICON-D2 menerbitkannya, ICON global tidak, sehingga di luar Eropa Anda mendapat ketinggian titik beku dan ketebalannya, tetapi bukan batasnya.

Laut — kondisi laut#

{
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "wave_height": [0.32],
    "wave_direction": [264.3],
    "wave_period": [3.79],
    "wave_peak_period": [4.21]
  }
}

Tinggi gelombang adalah tinggi signifikan — rata-rata sepertiga gelombang tertinggi, kira-kira sama dengan yang dilaporkan pengamat di laut. Gelombang tunggal bisa mencapai sekitar dua kali lipatnya, dan angka itulah yang penting bila Anda memutuskan melaut atau tidak. Arahnya adalah arah dari mana gelombang datang, seperti arah angin.

Sungai#

Ia menjawab apa yang tidak bisa dijawab model cuaca mana pun: bukan berapa banyak hujan yang turun di hulu, melainkan berapa banyak air yang tiba di sini — angka yang berbeda, dipisahkan dari hujan oleh sebuah daerah aliran, oleh kondisi kelembapan tanah, dan oleh satu-dua hari waktu tempuh.

{
  "disclaimer": "Information only. Only national and regional authorities
                 are authorised to issue flood warnings.",
  "daily": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "river_discharge": [4.953],
    "soil_wetness_index": [0.448]
  }
}