Başlarken

Bu nedir#

Climate Memory, tek bir API anahtarıyla iki sunucudan üç ürün sunar.

Tek sunucu yerine iki sunucu var, çünkü derece günler farklı bir maliyet profiline sahip farklı bir arşivi okuyor; ikisini ayırmak birinin yavaşlaması durumunda diğerinin yavaşlamamasını sağlıyor. Doğru temel URL'yi kopyalamanın ötesinde bunu dert etmeniz gerekmez.

İlk çağrınız#

Üç adım. Tamamı yaklaşık bir dakika sürer.

1. Anahtar alın

developers.climatememory.com/signin adresinde hesap açın. Ücretsiz plan kart istemez, ayda 10 000 kredi verir ve anahtarınız hemen ekranda görünür. Anahtarı bir ortam değişkeninde tutun — aşağıdaki örneklerin hepsi $API_KEY okur.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Çağrıyı yapın

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. Yanıtı okuyun

Bütün seriler sütun yönelimli döner — nesne listesi değil, tek bir time dizinini paylaşan paralel diziler. Nedenini ve nasıl okunacağını yanıt kuralları bölümünde bulursunuz.

Kimlik doğrulama#

Anahtarınızı her istekte X-API-Key başlığında gönderin. OAuth akışı, yenilenecek bearer token ya da hesaplanacak imza yoktur.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Anahtarlar özetlenerek saklanır. Birini kaybederseniz kurtarılmaz, döndürülür — size yeniden gösteremeyiz, çünkü bizde yok. Döndürme konsoldadır ve anında yeni bir anahtar üretir.

Scope'lar

Bir anahtar scope'lar taşır ve hangilerini taşıyacağına plan karar verir. Scope'larınızın dışındaki bir uç noktayı çağırmak 403 scope_denied döndürür — bu bir anahtar sorunu değil, plan sorunudur ve mesaj da bunu söyler.

Coğrafi kodlama uç noktaları bunların hiçbirini gerektirmez. Geçerli herhangi bir anahtar, hangi planda olursa olsun bir yer adını çözer; çünkü buradaki her ürünün yanıt verebilmesi için önce bir koordinata ihtiyacı vardır. Coğrafi kodlama bölümüne bakın.

Coğrafi kodlama#

Parametreler

Katalog, GeoNames'in P özellik sınıfının tamamıdır — nüfusa göre süzülmüş bir seçki değil, yeryüzündeki her yerleşim yeri, birkaç düzine kişilik mezralara kadar. 528 nüfuslu bir köy de içindedir.

Eşleşme asla dille sınırlanmaz

Sorgu; yerel ad, ASCII harf çevrimi ve bütün yerelleştirilmiş takma adlar üzerinde denenir, lang ne derse desin. Bu, kulağa geldiğinden önemlidir: yerlerin %98'inin hiçbir yerelleştirilmiş adı yoktur — Fransızca kataloğun %1,84'ünü kapsar — dolayısıyla dile göre süzülen bir arama başkentleri bulur, başka bir şey bulmaz. lang hangi adın döneceğini seçer ve sıralamayı etkiler; neyin uygun olduğuna asla karar vermez.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # Lille'den
GET /v1/geocode?q=bruxelles&lang=fr                     # egzonim, takma ad dizini üzerinden
GET /v1/geocode?q=zuesch&lang=de                        # umlaut açık yazımla

Sonuçlar nasıl sıralanır

Her sonuç bir score, near verilmişse bir de distance_km taşır. Sıralama dört sinyali birleştirir: adın ne kadar iyi eşleştiği, yerin ne kadar önemli olduğu, near noktasına ne kadar yakın olduğu ve eşleşen adın istenen dilde olup olmadığı.

near neden var. İki Ramillies vardır — Valon Brabant'ta 5 749 nüfuslu, Hauts-de-France'ta 528 nüfuslu olanı; aralarında 126 km var. Soyut olarak hiçbiri doğru yanıt değildir. near olmadan büyük olan döner; Lille'den bakıldığında Fransız olanı döner.

Önem yalnızca nüfus değildir. Kataloğun %90,7'sinde kayıtlı nüfus yoktur — GeoNames bazı ülkeler için hiç nüfus yayımlamaz — bu yüzden nüfus yokken sıralamayı yerin türü taşır (ulusal başkent, idari birim merkezi, sıradan yerleşim, mahalle).

Umlautlar atılmaz, açılarak yazılır. Aksan işareti olmayan bir Alman ya da Danimarka klavyesi Züsch için Zuesch, Köln için Koeln yazar. GeoNames bu yazımı taşımaz — ASCII biçimi, umlaut açılmak yerine kaldırılmış hâliyle Zusch'tur — bu yüzden burada üretilir. Her iki yazım da yere ulaşır ve sonuç iki durumda da gerçek adı gösterir.

Şehir araması#

/v1/cities/search, /v1/geocode'dan eskidir ve üzerine hâlihazırda bir şey kurmuş olanlar için sözleşmesini korur: yalnızca ASCII adı eşleştirir ve nüfusa göre sıralar.

/v1/cities/nearest ters yöndür ve bir GPS konumunu, sonra şehir uç noktalarına verebileceğiniz bir şehir slug'ına çeviren şeydir. lat, lon ve isteğe bağlı bir max_km alır.

İkisi de /v1/geocode ile aynı coğrafi kodlama tavanına sayılır ve hiçbiri kredi harcamaz.

Yanıt kuralları#

Altı kural bütün uç noktalarda geçerlidir. Bir kez öğrenin, bu belgelerin geri kalanı yalnızca alan adlarından ibarettir.

1. Seriler sütundur, satır değil

Her zaman serisi, nesne dizisi yerine tek bir time dizinini paylaşan paralel diziler kümesidir:

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

Her dizinin i indisi aynı anı betimler. Bu, satır biçimine göre telde üç ila beş kat daha küçüktür, dönüşüme gerek kalmadan doğrudan bir veri çerçevesine ya da grafik kütüphanesine çözülür ve Open-Meteo biçimine göre yazılmış istemcilerin zaten beklediği şeydir. Satır satır dolaşmak için:

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

2. Zamanlar açık ofsetli ISO 8601'dir

Her zaman. 2026-08-01T00:00:00+00:00; asla çıplak bir yerel dize ya da Unix tamsayısı değil. Bir timezone geçtiğinizde yanıttaki ofset o dilimin ofsetidir — böylece dize tek başına kesindir ve neyi varsaydığımızı bilmek zorunda kalmazsınız.

3. Birimler SI'dir, sabittir ve pazarlığa açık değildir

°C, mm, m/s, hPa, W/m², metre. Bilerek units=imperial diye bir parametre yok: birim anahtarı, anlamı başka bir alana bağlı olan bir alandır ve kimsenin gözden geçirmediği bir yapılandırma değişikliğinden sonra çağıranın Celsius eksenine Fahrenheit çizmesi tam da böyle olur. Dönüşümü, okuyucunun bulunduğu yerde, kendi kenarınızda yapın.

Alışılmadık birimler taşıyan uç noktalar, hatırlamanızı beklemek yerine yanıtta bunları açıkça adlandıran bir units bloğu gönderir.

4. null "bilinmiyor" demektir, asla "sıfır" değil

Eksik bir saat dizide null'dur ve indisler hizalı kalsın diye yerini korur. Sessizce 0 ile doldurulmaz — yağış için bu ikisi zıt iddialardır ve biri kuraklık hakkında söylenmiş bir yalandır.

5. Her yanıt nereden geldiğini söyler

Veriyle birlikte bir source bloğu (hava durumu) ya da bir quality bloğu (arşivler) yolculuk eder: hangi model veya koşu yanıtladı, ne kadar eski, dönem ne kadar eksiksizdi. Tazeliği saate bakarak çıkarmak zorunda kalmazsınız.

6. Bayat, hiç yoktan iyidir

En yeni model koşumuz beklenenden eskiyse 503 döndürmek yerine yine de yanıt veririz — source bloğunda "stale": true ve data_age_hours ile. Sekiz saatlik bir tahmin, bir hatadan daha yararlıdır. Tazelik sizin için belirleyiciyse bayrağa bakın; değilse yok sayın.

Hız sınırları, krediler ve kota#

Üç bağımsız sınır geçerlidir ve bilerek farklı biçimlerde devreye girerler. Başarılı her yanıt nerede durduğunuzu bildirir:

İstek değil, kredi

Önbellekten gelen bir şehir tahmini 3 ms'lik bir okumadır. Beş yüz saha için on yıllık saatlik derece gün değildir. İsteğe göre fiyatlamak, bir çağıranın kotasının içinde kalıp ödediğinden fazlasına mal olmasına tümüyle yasal biçimde izin verirdi — bu yüzden bir çağrının maliyeti, ne kadar arşiv taşıdığına bağlıdır.

Her birine çarptığınızda ne yapmalı

Kota döneminiz abonelik tarihinizden bir sonraki ayın aynı gününe kadar sürer — Stripe'ın faturaladığı dönem — ve sayaç her seferinde baştan başlar. X-Quota-Resets-At bu tarihi her yanıtta taşır; ayın birini varsaymak yerine onu okuyun. Aboneliği olmayan hesaplar takvim ayını izler.

Hatalar#

Her hata, her iki sunucuda da aynı biçimdedir:

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

Liste bundan ibarettir ve her yapıda kaynak kodla karşılaştırılır: burada yayımlanmış ama hiçbir işleyicinin fırlatmadığı bir kod testleri düşürür; bu tabloda olmayan bir kodu fırlatan bir işleyici de öyle. Yukarıda olmayan bir kodla karşılaşırsanız bu, bu sayfanın hatasıdır; özel olarak ele almanız gereken bir değer değil.

İşe yarayan bir yeniden deneme politikası

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # sıfırlanana kadar hiçbir şey değişmez
    if code == "geocode_quota_exceeded":
        return False              # ve durmayın: krediler hâlâ çalışıyor
    if code in RETRY:
        return attempt < 5
    return status >= 500

Doğruluk — ne beklemeli#

Sınırları üretimde keşfetmeniz yerine beklentileri baştan doğru kurmayı yeğleriz.

Tahminin güçlü olduğu yerler

Sıcaklık, basınç, sinoptik rüzgâr, nem, güneşlenme. 24 saatte 2 m sıcaklık hatası tipik olarak 1–1,5 °C civarındadır. ECMWF dünyanın en iyi küresel deterministik modelidir ve aldığınız da odur.

Zayıf olduğu yerler

Konvektif fırtınalar — 28 km'lik bir hücre bir gök gürültülü fırtınayı çözemez, 3 km bile ancak ima eder. Sağanakların tam yeri ve zamanı. Modelin çözünürlüğünün altındaki kıyı ve dağ mikro iklimi. Arazi düzeltmesinin modellemediği deniz meltemleri ve vadi soğuk hava göllenmeleri.

Coğrafi dürüstlük

Fransa, Almanya, ABD ve Kanada'da 1,3–3 km'lik ulusal modeller sunuyoruz ve küçük bir köy gerçekten kendi ızgara hücresini alıyor. Avrupa'nın geri kalanında 6,5 km alıyorsunuz. Afrika, Orta Doğu ve Asya'nın çoğunda mevcut en iyi kamuya açık model 13–28 km'dir; yani sokağın değil, bölgenin havasını alırsınız. Arazi düzeltmesi bu farkı daraltır ama kapatmaz.

Derece günler

Izgara tabanlı yeniden analiz her yeri kapsar; 60 km içinde meteoroloji istasyonu bulunmayan konumlar dahil — istasyon tabanlı sağlayıcılara karşı üstünlüğü budur. Zayıflığı ise yeniden analizin olduğundan düşük okuduğu şehir merkezleridir; şehir uç noktaları kalibre edilmiş bir düzeltme uygular, koordinat uç noktaları uygulamaz.

İki alan tahminidir ve bunu söylemeyi yeğleriz

uv_index, ozon kolonundan değil, güneş yüksekliği ve geniş bantlı radyasyondan türetilir — kabaca ±1 birim doğrulukta. precipitation_probability_proxy bir olasılık değil, bir kestirimdir; gerçeği /v1/probability adresindedir. İkisi de alan referansında tam olarak açıklanmıştır.

Planlar#

Coğrafi kodlama bu tablonun dışındadır: hiçbir planda kredi harcamaz ve kredi başına beş istek şeklinde kendi tavanını taşır. Hız sınırları ve kota bölümüne bakın.

Yıllık ödemede iki ay bedavadır. Güncel katalog developers.climatememory.com/pricing adresindedir — o sayfa faturalama sistemini doğrudan okur; ikisi bir gün çelişirse o sayfa geçerlidir.

Hiçbir planda toplu dışa aktarma uç noktası yoktur. CSV dışa aktarma derece gün ve iklim arşivlerinde vardır, eşdeğer JSON çağrısıyla aynı aralıkla sınırlıdır ve yalnızca toplulaştırılmış satırlar döndürür — saatlik seriyi asla.

Atıf ve lisanslama#

Yukarıdaki iki uç nokta anahtar istemez; böylece bir kaynak değiştiğinde bayatlayacak bir dizeyi koda gömmek yerine bildirimi API'den üretebilirsiniz. Yanıtı veren belirli koşuya ait atıf da her veri yanıtında, source.attribution içinde ve X-Data-Attribution başlığında yolculuk eder.

Bu verileri kullandığınızı belirtebilirsiniz. Bu kuruluşlardan herhangi birinin ürününüzü ürettiğini, onayladığını ya da desteklediğini ima edemezsiniz.

Sorumluluk reddi

Tahminler garantisiz sunulur. Ne Avrupa Komisyonu, ne ECMWF, ne DWD, ne NOAA ne de Météo-France bu bilgilerin herhangi bir kullanımından sorumludur. Bunu, can, güvenlik ya da mal varlığının risk altında olduğu kararların tek dayanağı olarak kullanmayın.

Bir kısıtlamayı kaldırmak bizim elimizde değil: Copernicus lisansı sel uyarılarını ulusal ve bölgesel makamlara ayırır. Nehirler bölümüne bakın.