Mulai

Apa ini#

Climate Memory melayani tiga produk dari dua host, dengan satu kunci API.

Dua host, bukan satu, karena derajat-hari membaca arsip berbeda dengan profil biaya berbeda, dan memisahkannya membuat yang satu bisa lambat tanpa memperlambat yang lain. Anda tidak perlu memikirkannya lebih jauh selain menyalin URL dasar yang tepat.

Panggilan pertama Anda#

Tiga langkah. Semuanya memakan waktu sekitar satu menit.

1. Dapatkan kunci

Buat akun di developers.climatememory.com/signin. Paket gratis tidak meminta kartu, memberi Anda 10 000 kredit per bulan, dan kunci Anda langsung tampil di layar. Simpan di variabel lingkungan — semua contoh di bawah membaca $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Lakukan panggilan

curl -sH "X-API-Key: $API_KEY" \
  "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3"

import os, httpx

r = httpx.get(
    "https://api.climatememory.com/v1/forecast",
    params={"lat": 48.85, "lon": 2.35, "days": 3},
    headers={"X-API-Key": os.environ["API_KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["daily"]["temperature_2m_max"])

const res = await fetch(
  "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3",
  { headers: { "X-API-Key": process.env.API_KEY } },
);
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const data = await res.json();
console.log(data.daily.temperature_2m_max);

req, _ := http.NewRequest("GET",
    "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3", nil)
req.Header.Set("X-API-Key", os.Getenv("API_KEY"))

res, err := http.DefaultClient.Do(req)
if err != nil { return err }
defer res.Body.Close()

var out struct {
    Daily struct {
        TemperatureMax []float64 `json:"temperature_2m_max"`
    } `json:"daily"`
}
json.NewDecoder(res.Body).Decode(&out)

3. Baca jawabannya

Semua deret kembali berorientasi kolom — larik paralel yang berbagi satu indeks time, bukan daftar objek. Lihat konvensi respons untuk alasannya dan cara membacanya.

Autentikasi#

Kirim kunci Anda pada header X-API-Key di setiap permintaan. Tidak ada alur OAuth, tidak ada bearer token yang perlu disegarkan, dan tidak ada tanda tangan yang perlu dihitung.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Kunci disimpan dalam bentuk hash. Jika Anda kehilangan satu, kunci itu dirotasi, bukan dipulihkan — kami tidak bisa menampilkannya lagi, karena kami memang tidak memilikinya. Rotasi ada di konsol dan langsung menerbitkan kunci baru.

Scope

Sebuah kunci membawa scope, dan paketlah yang menentukan scope mana. Memanggil endpoint di luar scope Anda mengembalikan 403 scope_denied — itu masalah paket, bukan masalah kunci, dan pesannya mengatakan demikian.

Endpoint geocoding tidak memerlukan satu pun dari scope itu. Kunci valid mana pun bisa menyelesaikan nama tempat, di paket mana pun, karena setiap produk di sini butuh koordinat sebelum bisa menjawab apa pun. Lihat geocoding.

Geocoding#

Parameter

Katalognya adalah kelas fitur P dari GeoNames secara utuh — setiap tempat berpenduduk di bumi, sampai dusun berisi beberapa puluh orang, bukan cuplikan yang disaring berdasarkan jumlah penduduk. Desa berpenduduk 528 jiwa pun ada di dalamnya.

Pencocokan tidak pernah dibatasi bahasa

Kueri diuji terhadap nama lokal, transliterasi ASCII-nya, dan semua alias terlokalkan, apa pun isi lang. Itu lebih penting daripada kedengarannya: 98 % tempat sama sekali tidak punya nama terlokalkan — bahasa Prancis mencakup 1,84 % katalog — sehingga pencarian yang disaring per bahasa hanya akan menemukan ibu kota dan tidak lebih. lang memilih nama mana yang dikembalikan dan memengaruhi peringkat; ia tidak pernah menentukan apa yang layak muncul.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # dari Lille
GET /v1/geocode?q=bruxelles&lang=fr                     # eksonim, lewat indeks alias
GET /v1/geocode?q=zuesch&lang=de                        # umlaut ditulis panjang

Bagaimana hasil diperingkat

Setiap hasil membawa score dan, jika near diberikan, distance_km. Peringkat menggabungkan empat sinyal: seberapa cocok namanya, seberapa penting tempatnya, seberapa dekat ke near, dan apakah nama yang cocok berada dalam bahasa yang diminta.

Mengapa near ada. Ada dua Ramillies — 5 749 penduduk di Brabant Wallonia, 528 di Hauts-de-France, terpisah 126 km. Tidak ada yang benar secara abstrak. Tanpa near yang dikembalikan adalah yang lebih besar; dari Lille, yang dikembalikan adalah yang di Prancis.

Ketermukaan bukan sekadar jumlah penduduk. 90,7 % katalog tidak punya catatan penduduk — GeoNames sama sekali tidak menerbitkannya untuk sebagian negara — sehingga jenis tempat (ibu kota negara, pusat pemerintahan wilayah, tempat biasa, permukiman) yang memikul peringkat di mana pun data penduduk tidak ada.

Umlaut ditulis panjang, bukan dibuang. Papan ketik Jerman atau Denmark tanpa tanda diakritik menulis Zuesch untuk Züsch dan Koeln untuk Köln. GeoNames tidak membawa ejaan itu — bentuk ASCII-nya adalah Zusch, dengan umlaut dihapus alih-alih dipanjangkan — jadi ejaan itu dibuat di sini. Kedua ejaan sampai ke tempat yang benar, dan hasilnya tetap menampilkan nama sebenarnya.

Pencarian kota#

/v1/cities/search lebih tua daripada /v1/geocode dan mempertahankan kontraknya untuk pemanggil yang sudah membangun di atasnya: ia hanya mencocokkan nama ASCII dan mengurutkan berdasarkan jumlah penduduk.

/v1/cities/nearest adalah arah sebaliknya, dan itulah yang mengubah posisi GPS menjadi slug kota yang lalu bisa Anda berikan ke endpoint per kota. Ia menerima lat, lon, dan max_km opsional.

Keduanya dihitung ke plafon geocoding yang sama dengan /v1/geocode, dan tidak satu pun memakan kredit.

Konvensi respons#

Enam aturan berlaku di semua endpoint. Pelajari sekali, dan sisa dokumentasi ini hanyalah nama-nama field.

1. Deret berupa kolom, bukan baris

Setiap deret waktu adalah sekumpulan larik paralel yang berbagi satu indeks time, bukan larik objek:

"hourly": {
  "time":           ["2026-08-01T00:00:00+00:00", "2026-08-01T01:00:00+00:00"],
  "temperature_2m": [18.4, 18.1],
  "precipitation":  [0.0, 0.2]
}

Indeks i pada setiap larik menggambarkan momen yang sama. Bentuk ini tiga sampai lima kali lebih kecil di jaringan dibanding bentuk baris, langsung terurai menjadi dataframe atau pustaka grafik tanpa transformasi, dan inilah yang sudah diharapkan klien bergaya Open-Meteo. Untuk menelusurinya sebagai baris:

rows = zip(h["time"], h["temperature_2m"], h["precipitation"])

2. Waktu memakai ISO 8601 dengan offset eksplisit

Selalu. 2026-08-01T00:00:00+00:00, bukan string lokal telanjang dan bukan bilangan bulat Unix. Saat Anda mengirim timezone, offset pada respons adalah offset zona tersebut — sehingga string itu sendiri sudah tidak ambigu dan Anda tidak perlu tahu apa yang kami asumsikan.

3. Satuan memakai SI, tetap, dan tidak dinegosiasikan

°C, mm, m/s, hPa, W/m², meter. Tidak ada parameter units=imperial, dan itu disengaja: sakelar satuan adalah field yang maknanya bergantung pada field lain, dan begitulah seorang pemanggil berakhir menggambar Fahrenheit pada sumbu Celsius setelah perubahan konfigurasi yang tak ditinjau siapa pun. Konversikan di sisi Anda, tempat pembacanya berada.

Endpoint dengan satuan tak lazim mengirimkan blok units pada respons yang menyebutkannya secara eksplisit, alih-alih mengandalkan ingatan Anda.

4. null berarti "tidak diketahui", tidak pernah "nol"

Jam yang hilang menjadi null di dalam larik, tetap menempati posisinya agar indeks tetap sejajar. Ia tidak pernah diam-diam diisi 0 — untuk curah hujan keduanya adalah klaim yang berlawanan, dan salah satunya adalah kebohongan tentang kekeringan.

5. Setiap respons menyebut asalnya

Blok source (cuaca) atau blok quality (arsip) menyertai data: model atau run mana yang menjawab, seberapa lama usianya, seberapa lengkap periodenya. Anda tidak perlu menyimpulkan kesegaran dari jam.

6. Basi lebih baik daripada tidak ada

Jika run model terbaru kami lebih tua daripada seharusnya, kami tetap menjawab — dengan "stale": true dan data_age_hours di blok source — alih-alih mengembalikan 503. Prakiraan berumur delapan jam lebih berguna daripada sebuah kesalahan. Periksa penandanya jika kesegaran itu penting bagi Anda; abaikan jika tidak.

Batas laju, kredit, dan kuota#

Tiga batas independen berlaku, dan ketiganya sengaja gagal dengan cara berbeda. Setiap respons yang berhasil melaporkan posisi Anda:

Kredit, bukan permintaan

Prakiraan kota dari cache adalah pembacaan 3 md. Sepuluh tahun derajat-hari per jam untuk lima ratus lokasi bukan. Menagih per permintaan akan membuat pemanggil tetap berada dalam kuotanya namun memakan biaya lebih besar daripada yang ia bayar, sepenuhnya secara sah — jadi biaya sebuah panggilan bergantung pada seberapa banyak arsip yang digerakkannya.

Apa yang harus dilakukan saat menabrak masing-masing

Periode kuota Anda berjalan dari tanggal langganan sampai tanggal yang sama pada bulan berikutnya — periode yang ditagih Stripe — dan penghitungnya dimulai penuh lagi setiap kali. X-Quota-Resets-At membawa tanggal itu di setiap respons, jadi bacalah alih-alih menganggapnya tanggal 1. Akun tanpa langganan mengikuti bulan kalender.

Kesalahan#

Setiap kesalahan berbentuk sama, di kedua host:

{
  "error": {
    "code": "range_too_long",
    "message": "Requested span is 14.0 years; the maximum per request is 10.",
    "max_years": 10
  }
}

Itulah seluruh daftarnya, dan ia diperiksa terhadap kode sumber pada setiap build: kode yang diterbitkan di sini tetapi tidak dilempar handler mana pun akan menggagalkan rangkaian uji, begitu pula handler yang melempar kode yang tidak ada di tabel ini. Jika Anda menemui kode yang tidak tercantum di atas, itu bug halaman ini, bukan nilai yang perlu Anda tangani khusus.

Kebijakan ulang-coba yang berhasil

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # tidak ada yang berubah sampai reset
    if code == "geocode_quota_exceeded":
        return False              # dan jangan berhenti: kredit masih jalan
    if code in RETRY:
        return attempt < 5
    return status >= 500

Akurasi — apa yang bisa diharapkan#

Kami lebih suka menetapkan harapan dengan benar daripada membiarkan Anda menemukan batasnya di produksi.

Di mana prakiraan ini kuat

Suhu, tekanan, angin sinoptik, kelembapan, lama penyinaran matahari. Kesalahan khas suhu 2 m pada 24 jam sekitar 1–1,5 °C. ECMWF adalah model deterministik global terbaik di dunia dan itulah yang Anda dapatkan.

Di mana ia lebih lemah

Badai konvektif — sel 28 km tidak bisa memisahkan satu badai petir, dan 3 km pun hanya mengisyaratkannya. Letak dan waktu persis hujan lokal. Iklim mikro pesisir dan pegunungan di bawah resolusi model. Angin laut dan kantong udara dingin lembah, yang tidak dimodelkan oleh koreksi medan.

Kejujuran geografis

Di Prancis, Jerman, AS, dan Kanada kami melayani model nasional 1,3–3 km, dan sebuah desa kecil benar-benar mendapat sel gridnya sendiri. Di bagian Eropa lainnya Anda mendapat 6,5 km. Di Afrika, Timur Tengah, dan sebagian besar Asia, model publik terbaik yang tersedia adalah 13–28 km, jadi Anda mendapat cuaca kawasan, bukan cuaca jalan Anda. Koreksi medan mempersempit selisih itu tetapi tidak menutupnya.

Derajat-hari

Reanalisis bergrid mencakup semua tempat, termasuk lokasi tanpa stasiun cuaca dalam radius 60 km — itulah kelebihannya dibanding penyedia berbasis stasiun. Kelemahannya adalah pusat kota, yang dibaca terlalu rendah oleh reanalisis; endpoint per kota menerapkan koreksi terkalibrasi, endpoint koordinat tidak.

Dua field adalah perkiraan, dan kami lebih suka mengatakannya

uv_index diturunkan dari elevasi matahari dan radiasi pita lebar, bukan dari kolom ozon — akurat kira-kira ±1 satuan. precipitation_probability_proxy adalah perkiraan, bukan probabilitas; yang sungguhan ada di /v1/probability. Keduanya dijelaskan lengkap di referensi field.

Paket#

Geocoding berada di luar tabel ini: tidak memakan kredit di paket mana pun, dan punya plafonnya sendiri sebesar lima permintaan per kredit. Lihat batas laju dan kuota.

Penagihan tahunan berarti dua bulan gratis. Katalog terkini ada di developers.climatememory.com/pricing — halaman itu membaca sistem penagihan secara langsung, jadi jika keduanya pernah berbeda, halaman itulah yang benar.

Tidak ada endpoint ekspor massal di paket mana pun. Ekspor CSV tersedia pada arsip derajat-hari dan iklim, dibatasi pada rentang yang sama dengan panggilan JSON setara, dan hanya mengembalikan baris teragregasi — tidak pernah deret per jam.

Atribusi dan lisensi#

Kedua endpoint di atas tidak butuh kunci, jadi Anda bisa merender pemberitahuannya dari API alih-alih menanam string yang akan basi ketika sebuah sumber berubah. Atribusi untuk run tertentu yang menjawab juga menyertai setiap respons data, di source.attribution dan di header X-Data-Attribution.

Anda boleh menyatakan bahwa Anda memakai data ini. Anda tidak boleh menyiratkan bahwa salah satu organisasi tersebut membuat, menyetujui, atau mendukung produk Anda.

Penafian

Prakiraan disediakan tanpa jaminan. Baik Komisi Eropa, ECMWF, DWD, NOAA, maupun Météo-France tidak bertanggung jawab atas penggunaan informasi ini. Jangan menjadikannya satu-satunya dasar keputusan ketika nyawa, keselamatan, atau harta benda dipertaruhkan.

Satu pembatasan bukan milik kami untuk dilepaskan: lisensi Copernicus menyerahkan peringatan banjir kepada otoritas nasional dan regional. Lihat sungai.