API Climă
Optzeci și șapte de ani de climă zilnică, peste tot pe uscat, dintr-o singură arhivă — de la 1 ianuarie 1940 până la mai puțin de o săptămână în urmă, pe grila ERA5 la 0,25° (circa 28 km). Răspunde la e normal asta?, cu dovezi.
Climă zilnică#
climate2 credite, +1 pentru fiecare perioadă completă de 365,25 zile din intervalTreisprezece câmpuri zilnice pentru orice coordonată de uscat, din 1940 până săptămâna trecută.
Parametri
| Parametru | Tip | Implicit | Descriere |
|---|---|---|---|
lat | float | — | Obligatoriu. Orice coordonată pe uscat; arhiva e globală. |
lon | float | — | Obligatoriu. |
start | ISO date | 1 ianuarie al anului de sfârșit | Intervalul e plafonat per cerere — vedeți Planuri. |
end | ISO date | ultima zi a arhivei | |
fields | csv | temperatură și precipitații | Întrebați /v1/climate/fields la ce poate răspunde rularea aceasta. |
series | bool | true | Include valorile zi de zi. Puneți-l pe false când vreți doar agregatele. |
format | string | json | json sau csv. CSV-ul e o funcție a planurilor plătite și întoarce rândurile lunare. |
Asta nu e istoricul orar cu un
GROUP BY în față. Câmpurile zilnice sunt derivate o singură dată, la
ingerare, pe o graniță de zi aleasă pentru fizică, nu pentru comoditate, iar
câmpurile derivate — temperatura resimțită, durata de strălucire a soarelui,
umiditatea medie — sunt calculate din seria orară completă, nu din extremele
zilnice.
Zilele se taie la miezul nopții solar, nu la fusul orar
politic. Decalajul este round(longitude / 15).
E o alegere deliberată și se poate măsura: agregarea pe UTC deplasează minimul zilnic cu 2,1 °C la Alice Springs, pentru că minimul cade chiar înainte de zori. Un fus orar politic ar fi și mai rău — două celule vecine de o parte și de alta a unei granițe și-ar avea zilele tăiate în momente diferite, iar o hartă a maximelor zilnice ar desena conturul fusurilor.
Valorile sunt ale celulei de grilă, nu ale punctului. Nu ajustăm temperatura la altitudinea dumneavoastră exactă. Furnizorii care o fac vor diferi deci de noi cu câteva zecimi de grad la aceeași coordonată — până la 0,4 °C în propriile noastre măsurători — și niciuna dintre cifre nu e greșită. A noastră e ce spune reanaliza pentru celula aceea; a lor e valoarea aceea plus un gradient termic aplicat unei diferențe de altitudine. Publicăm celula ca să știți ce primiți: vedeți acoperire și celule.
Agregate lunare#
climate2 credite, +1 pentru fiecare perioadă completă de 365,25 zile din intervalAceleași câmpuri agregate pe luni calendaristice.
Sume pentru acumulări, medii și extreme pentru rest. Același preț ca seria zilnică, pentru că citește aceeași coloană.
Cereți-le când o cifră lunară e ceea ce desenați de fapt, în loc să aduceți de treizeci de ori mai multe date și să le reduceți singuri — transferul e partea lentă, nu aritmetica.
Clima unui loc, într-un singur apel#
climate3 credite, +1 pentru fiecare perioadă completă de 365,25 zile din intervalNormale lunare, serie anuală, recorduri, tendințe și Köppen — fără limită de interval.
Parametri
| Parametru | Tip | Implicit | Descriere |
|---|---|---|---|
lat | float | — | Obligatoriu. |
lon | float | — | Obligatoriu. |
start | ISO date | prima zi a arhivei | A cere toată înregistrarea e modul normal de a folosi asta. |
end | ISO date | ultima zi a arhivei | |
daily | bool | false | Adaugă day_normals: normala fiecărei zile calendaristice a anului pe fereastra dumneavoastră, cu numărul de observații din spatele fiecăreia. |
Tot ce spune o pagină de climă despre un loc, deja redus: douăsprezece normale lunare, un rând pentru fiecare an calendaristic complet, recordurile absolute cu datele la care au căzut, tendința de încălzire prin cele mai mici pătrate cu semnificația ei și codul Köppen-Geiger. Pentru orice coordonată de uscat de pe Pământ.
Prețul depinde de interval, iar intervalul implicit e arhiva
întreagă. Tarifat la 3 credite, +1 pentru fiecare perioadă completă de 365,25 zile din interval — deci un
apel fără start acoperă de la 1940 până azi și
costă 89 credite, nu unul. Pe planul
gratuit asta înseamnă cam 110 apeluri pe lună.
E totuși modul ieftin de a obține răspunsul ăsta: asamblarea lui pe cont propriu ar cere nouă apeluri plafonate la /v1/climate/daily pe același interval, care laolaltă costă mai mult și întorc treizeci și una de mii de rânduri pe care apoi tot dumneavoastră trebuie să le reduceți. Dar nu e o simplă consultare, iar o pagină care îl apelează la fiecare vizitator va goli o cotă. Puneți-l în cache — răspunsul pentru o coordonată se schimbă cel mult o dată pe zi.
Transmiteți start când nu vă trebuie toată înregistrarea:
treizeci de ani costă 32 în loc de
89.
Aici nu există limită de interval, spre deosebire de
/v1/climate/daily. Limita aceea există pentru că un
apelant care poate trage seria zi de zi poate reconstitui arhiva; endpointul
acesta nu întoarce nicio serie. Înregistrarea completă se întoarce în circa
62 kB — 100 kB cu daily=true — față de cele treizeci și una de mii
de rânduri zilnice din care a fost redusă, deci nu reconstituie nimic. O singură
cerere înlocuiește cele nouă apeluri zilnice plafonate pe care același răspuns
le-ar cere altfel.
daily=true nu e același lucru cu normals?daily=true
Și tocmai în asta stă diferența. Endpointul normalelor face media pe o fereastră OMM de treizeci de ani; acesta face media pe fereastra pe care ați cerut-o — implicit, toată arhiva.
E singurul mod de a spune „9,4 °C peste normal pentru un 30 iulie” cu
optzeci și șapte de ani în spatele afirmației, nu cu treizeci. Fiecare zi poartă
numărul ei de eșantioane, deci lărgirea la o normală centrată pe cincisprezece
zile se scrie Σ(mean·samples) / Σ(samples) — exact, și fără o a doua
cerere.
Două convenții de știut înainte să comparați cu altă sursă
Un an calendaristic intră în seria anuală și în tendință doar dacă arhiva conține cel puțin 360 din zilele lui, deci anul în curs e exclus. O jumătate de an se citește ca o prăbușire a precipitațiilor și trage după ea o dreaptă de tendință.
trends este null sub zece ani compleți. Sub atât, o
pantă e zgomot meteorologic deghizat în semnal climatic, iar noi preferăm să nu
publicăm nimic decât o cifră greșită spusă cu siguranță. Din același motiv,
fiecare tendință poartă propriul p_value și indicatorul
significant — citiți-le înainte să citați panta.
Normale OMM#
normals3 crediteO medie pe treizeci de ani pe o perioadă de referință OMM.
Parametri
| Parametru | Tip | Implicit | Descriere |
|---|---|---|---|
lat | float | — | Obligatoriu. |
lon | float | — | Obligatoriu. |
period | string | 1991-2020 | 1991-2020 sau 1961-1990. Amândouă sunt perioade de referință OMM. |
fields | csv | temperatură și precipitații | |
daily | bool | false | Include cele 366 de normale pe zi cu dispersiile lor, plus recordul de cald și de frig pentru fiecare zi calendaristică. |
O normală nu e media perioadei pe care s-a nimerit s-o cereți. E o medie pe treizeci de ani, pe o fereastră fixată de Organizația Meteorologică Mondială, astfel încât două persoane care citează o normală să citeze același lucru.
Asta cere scope-ul normals, pe care
arhiva zilnică nu îl cere. O cheie care citește fără
probleme /v1/climate/daily poate primi totuși aici
403 scope_denied — vedeți Planuri ca să aflați
ce treaptă îl include.
Dacă ce vreți e „normala pe toată înregistrarea”, nu pe o fereastră OMM,
folosiți în schimb /v1/climate/summary — cere doar
scope-ul climate și vă dă optzeci și șapte de ani în loc de
treizeci.
Compararea a două normale#
normals6 crediteAmbele perioade OMM și schimbarea dintre ele, într-un singur apel.
Asta e întrebarea pe care o pun de fapt cei mai mulți când cer o normală — nu „ce e normal aici”, ci „cu cât s-a mutat normalul”.
Răspunsul într-o singură cerere garantează că cele două jumătăți nu pot veni din rulări diferite, ceea ce e exact modul de eșec al calculului făcut singur din două apeluri: arhiva avansează între ele, iar diferența pe care o publicați conține atunci o schimbare de versiune pe lângă o schimbare climatică.
Acoperire, câmpuri și celule#
Rularea servită și datele pe care le acoperă. Fără cheie.
La ce poate răspunde rularea aceasta, cu unități, și care câmpuri sunt derivate. Fără cheie.
climate1 creditCe celulă răspunde pentru un punct și cât de departe este.
Termenii de licență pentru arhiva aceasta. Fără cheie.
cells/resolve răspunde la întrebarea care ar trebui pusă
oricărui produs pe grilă înainte să fie crezut: ce celulă citesc de fapt și
cât de departe e de punctul despre care am întrebat? La 28 km, distanța
aceea poate fi de 20 km, iar a o ști e diferența dintre a cita o cifră și a o
cita responsabil.
fields are același contract ca
/v1/historical/variables: enumeră ce conține
rularea, nu ce ar putea conține produsul cândva, deci un client construit după
el nu se strică atunci când arhiva crește.
Fixați celula, nu coordonata, atunci când o referință trebuie să rămână comparabilă de-a lungul anilor. O coordonată e stabilă, dar celula care o servește s-ar muta dacă grila s-ar schimba vreodată — iar o referință care se mută în tăcere e exact modul de eșec pe care endpointul acesta există ca să-l prevină. API-ul de grade-zile are același tipar, cu o cale dedicată: vedeți fixarea unei celule.