Memulai cdsapi untuk Mengunduh ERA5 dari Nol

Mengapa Akses ERA5 Butuh Setup Awal

Tutorial ERA5 di blog ini selalu dimulai dengan satu baris yang sama: c.retrieve(...). Tapi sebelum baris itu jalan, ada satu kali setup yang harus dilakukan — mendaftar akun Copernicus, menerima lisensi data, memasang cdsapi, dan menyimpan API key. Sekali beres, semua tutorial ERA5 berikutnya tinggal python tutorial.py dan jalan.

ERA5 berbeda dari file biasa yang bisa di-wget. Datasetnya hidup di Copernicus Climate Data Store (CDS) — server asinkron yang menerima permintaan, menaruh di antrian, lalu memproses dan mengirimkan file NetCDF kembali. Untuk Indonesia bbox setahun penuh data 6-hourly, ukuran file sekitar 30 MB; antrian biasanya antara 30 detik sampai beberapa menit, tergantung load server.

Panduan ini menjelaskan setup dari nol. Setelah selesai, kunci API ada di ~/.cdsapirc, cdsapi ter-install, dan permintaan pertama menghasilkan file NetCDF ERA5 yang bisa dibuka dengan xarray. Total waktu setup pertama kali sekitar 15 menit; semuanya gratis.

Membuat Akun Copernicus CDS

Akses CDS gratis untuk riset dan penggunaan non-komersial, tapi butuh akun ECMWF. Tiga langkah ringkas:

1. Daftar di cds.climate.copernicus.eu — klik Login/Register, pilih Register a new user, isi email + password. Verifikasi email muncul beberapa menit kemudian.
2. Login dengan akun baru, lalu masuk ke halaman dataset ERA5 di Catalogue → ERA5 hourly data on single levels.
3. Di tab Download, scroll ke bagian paling bawah — ada checkbox "I agree to the terms" untuk lisensi dataset. Centang dan submit. Lisensi ini terpisah dari akun — harus diterima sekali per dataset (single-levels dan pressure-levels punya lisensi yang sama tapi accept-nya tetap per dataset).

Alur registrasi CDS sampai siap dipakai cdsapi. Verifikasi email dan accept-lisensi adalah dua langkah yang paling sering terlewat oleh pengguna baru.

Jangan lupa accept lisensi untuk reanalysis-era5-pressure-levels juga kalau berencana download data pressure-level (geopotential, suhu, angin di 850 hPa, dst). Tanpa accept, permintaan ke dataset itu gagal dengan pesan "Missing accepted licence".

Memasang cdsapi dan Menyimpan API Key

cdsapi adalah client Python resmi untuk CDS. Install dengan pip:

pip install cdsapi

Selanjutnya, ambil API key dari halaman profil CDS (login dulu). Di bagian Personal Access Token ada satu string panjang — ini key personal yang setara dengan password. Jangan share, jangan commit ke git.

Simpan key ke file ~/.cdsapirc (Linux/Mac) atau %USERPROFILE%\.cdsapirc (Windows). Format file sangat sederhana:

url: https://cds.climate.copernicus.eu/api
key: 12345678-abcd-1234-abcd-1234567890ab

Dua baris saja — URL endpoint CDS dan token. Untuk security, kunci permission file ke 0600 di Linux/Mac:

chmod 600 ~/.cdsapirc

Arsitektur cdsapi: ~/.cdsapirc dibaca sekali saat cdsapi.Client() dibuat. Setiap retrieve adalah POST ke queue dengan Bearer token, lalu GET file setelah job selesai.

Verifikasi setup dengan satu baris Python:

python -c "import cdsapi; c = cdsapi.Client(); print(c.url)"

Output harus mencetak URL CDS. Kalau muncul Missing/incomplete configuration file, file ~/.cdsapirc belum dibuat atau formatnya salah.

Membuat Permintaan Pertama

Sekarang bagian yang menarik — permintaan ERA5 pertama. Kita ambil 2m temperature setahun penuh 2024 dengan resolusi 6-hourly untuk wilayah Indonesia (bbox [6N, 95E, -11S, 141E]). Ukuran file final sekitar 30 MB; antrian CDS biasanya 30–90 detik untuk permintaan seukuran ini.

Snippet di bawah menerapkan pola if not os.path.exists(OUT) cache guard — kalau file sudah ada lokal, skip download. Berguna untuk run ulang script tanpa antri ulang ke CDS.

import os
import cdsapi
import xarray as xr

OUT = "era5_t2m_indonesia_2024_6h.nc"

if not os.path.exists(OUT):
    c = cdsapi.Client(quiet=True)
    c.retrieve(
        "reanalysis-era5-single-levels",
        {
            "product_type": "reanalysis",
            "variable": ["2m_temperature"],
            "year": "2024",
            "month": [f"{m:02d}" for m in range(1, 13)],
            "day":   [f"{d:02d}" for d in range(1, 32)],
            "time":  ["00:00", "06:00", "12:00", "18:00"],
            "area":  [6, 95, -11, 141],   # N, W, S, E — Indonesia
            "format": "netcdf",
        },
        OUT,
    )

ds = xr.open_dataset(OUT)
print(f"File   : {OUT}")
print(f"Size   : {os.path.getsize(OUT) / (1024*1024):.1f} MB")
print(f"Dims   : {dict(ds.sizes)}")
print(f"Var    : {list(ds.data_vars)}")
t2m_c = ds.t2m - 273.15  # K → °C
print(f"Range  : {float(t2m_c.min()):.1f} .. {float(t2m_c.max()):.1f} °C")
print(f"Mean Indonesia (rata-rata setahun): {float(t2m_c.mean()):.2f} °C")

File   : era5_t2m_indonesia_2024_6h.nc
Size   : 30.1 MB
Dims   : {'valid_time': 1464, 'latitude': 69, 'longitude': 185}
Var    : ['t2m']
Range  : 6.9 .. 39.3 °C
Mean Indonesia (rata-rata setahun): 27.31 °C

cdsapi.Client() membaca ~/.cdsapirc di background, lalu c.retrieve(...) adalah panggilan blocking — Python menunggu sampai CDS selesai memproses dan mengirim file. Argumennya: nama dataset, dict berisi spec request, dan path output. Pesan log CDS biasanya keluar ke stderr (queued, running, downloading) — saat snippet ini di-execute, kita pakai Client(quiet=True) untuk menekan output verbose.

Memahami CDS Queue dan Konvensi Permintaan

Ada beberapa konvensi yang sering bikin pengguna baru salah:

• Area = [N, W, S, E] — utara, barat, selatan, timur. Bukan [west, south, east, north] seperti beberapa API lain. Lintang utara positif, selatan negatif; bujur timur positif sampai 180, lalu negatif dari -180.
• year, month, day bisa string atau list of string. "2024" atau ["2024"] keduanya valid. Untuk multi-tahun atau multi-bulan, list lebih praktis: [str(y) for y in range(2020, 2025)].
• time selalu list of "HH:MM" string, bukan integer. ERA5 single-levels punya 24 timestep per hari; pilih subset (misal ["00:00", "06:00", "12:00", "18:00"]) untuk file lebih kecil.
• format: "netcdf" atau "grib". NetCDF lebih mudah dibuka dengan xarray; GRIB resmi tapi butuh cfgrib plugin.
• Queue time bervariasi 30 detik sampai beberapa menit, kadang lebih lama saat ada peak load (rilis dataset baru, deadline paper). Status job real-time bisa dilihat di dashboard Your requests di portal CDS.

Ukuran file naik linier dengan rentang waktu, jumlah variabel, dan luas area. Setahun penuh hourly 2m temperature untuk Indonesia bbox sekitar 30 MB. Untuk request besar (multi-tahun, multi-variabel, global), CDS kadang split job atau menolak — pecah jadi request lebih kecil.

Troubleshooting Permintaan yang Gagal

Beberapa error yang paling sering muncul saat setup awal:

• "Missing accepted licence" — login ke CDS, buka halaman dataset (single-levels atau pressure-levels), scroll ke bawah, centang lisensi.
• "401 Unauthorized" atau "Invalid API token" — API key di ~/.cdsapirc salah atau token sudah expired. Generate key baru di halaman profil dan paste ulang.
• "URLError" atau timeout** — koneksi network ke CDS bermasalah; cek firewall/proxy. CDS endpoint berada di cds.climate.copernicus.eu port 443.
• "Request not queued, server busy" — CDS sedang overloaded; tunggu 5-10 menit, request ulang.
• Job stuck di status queued lebih dari 1 jam — kemungkinan request terlalu besar atau ada bug di spec. Coba kurangi rentang waktu atau jumlah variabel, lalu submit ulang.

Untuk debugging lebih dalam, jalankan cdsapi.Client(debug=True) — output lebih verbose, termasuk full request payload dan response code dari CDS.

Langkah Lanjut

Setelah ~/.cdsapirc valid dan cdsapi.retrieve pertama berhasil, semua tutorial ERA5 di meteo.my.id langsung bisa diikuti — pola if not os.path.exists(OUT): c.retrieve(...) muncul di setiap tutorial sebagai snippet pertama. Bookmark halaman ini sebagai referensi setup; tutorial-tutorial lain mengasumsikan setup ini sudah beres.

Eksplorasi artikel meteorologi lainnya di meteo.my.id — temukan tutorial xarray, analisis ERA5 spesifik, dan teknik visualisasi atmosfer di https://meteo.my.id.

Referensi

• How to download ERA5 — Copernicus Knowledge Base — Panduan resmi ECMWF tentang instalasi cdsapi, konfigurasi ~/.cdsapirc, dan contoh permintaan untuk single-levels dan pressure-levels.
• Climate Data Store API how-to — Copernicus CDS — Halaman resmi CDS untuk setup API key dengan format ~/.cdsapirc terbaru.
• ERA5 data documentation — Copernicus Knowledge Base — Dokumentasi teknis ERA5 mencakup resolusi, level, daftar variabel, dan metode 4D-Var data assimilation yang dipakai.
• Hersbach et al. (2020): The ERA5 global reanalysis — Paper referensi ERA5 di Quarterly Journal of the Royal Meteorological Society yang mendeskripsikan seluruh sistem reanalisis secara komprehensif.