> ## Documentation Index
> Fetch the complete documentation index at: https://docs.climatifai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch historical and projected climate data
> Retrieve monthly temperature, precipitation, and soil moisture series for any LATAM coordinate, including CMIP6 future projections across four SSP scenarios.
The `/agri/climate` endpoint returns two complementary datasets for a given coordinate: a historical monthly series sourced from ERA5 reanalysis data, and a CMIP6 future projection for the scenario you choose. Both datasets share the same structure — monthly rows with temperature, precipitation, and soil moisture — making it straightforward to compare past conditions against projected future ones.
Send a `GET` request to `/agri/climate`. The `from` and `to` parameters define the historical period; `scenario` sets the CMIP6 emissions pathway for the projection.
```bash theme={null}
curl "https://api.climatifai.com/agri/climate?lat=-34.6&lon=-58.4&from=1991&to=2020&scenario=SSP3-7.0"
```
| Parameter | Type | Default | Description |
| ---------- | ------- | ---------- | ----------------------------------- |
| `lat` | float | required | Latitude (WGS 84, decimal degrees) |
| `lon` | float | required | Longitude (WGS 84, decimal degrees) |
| `from` | integer | `1991` | First year of the historical series |
| `to` | integer | `2020` | Last year of the historical series |
| `scenario` | string | `SSP3-7.0` | CMIP6 scenario for the projection |
The `historical` array contains one object per month for the requested year range. Each object covers a single calendar month across the full period — months are averaged over the years you specified (e.g., 1991–2020 gives you the 30-year climatological mean for each month).
```json theme={null}
"historical": [
{ "year": 1991, "month": 1, "temp_c": 24.1, "precip_mm": 112.3, "soil_moisture": 0.228 },
{ "year": 1991, "month": 2, "temp_c": 23.7, "precip_mm": 98.6, "soil_moisture": 0.221 },
{ "year": 1991, "month": 3, "temp_c": 21.4, "precip_mm": 87.2, "soil_moisture": 0.215 },
"..."
]
```
**Fields per row:**
| Field | Unit | Description |
| --------------- | ----- | -------------------------------------------- |
| `year` | — | Calendar year |
| `month` | — | Calendar month (1 = January) |
| `temp_c` | °C | Mean 2-metre air temperature |
| `precip_mm` | mm | Total precipitation |
| `soil_moisture` | m³/m³ | Volumetric soil water content (ERA5 layer 1) |
Any field may be `null` if the upstream data source did not return a value for that period.
The `projected` array has the same structure as `historical` but contains CMIP6 ensemble output for the future period associated with the chosen scenario. Rows represent monthly means in the mid- to late-21st century horizon provided by Open-Meteo's climate projection service.
```json theme={null}
"projected": [
{ "year": 2071, "month": 1, "temp_c": 27.3, "precip_mm": 95.1, "soil_moisture": 0.198 },
{ "year": 2071, "month": 2, "temp_c": 26.8, "precip_mm": 88.4, "soil_moisture": 0.191 },
{ "year": 2071, "month": 3, "temp_c": 24.9, "precip_mm": 76.0, "soil_moisture": 0.185 },
"..."
]
```
Compare `projected[n].temp_c` against `historical[n].temp_c` for the same month to estimate the projected temperature anomaly at your location.
Change the `scenario` query parameter to switch between CMIP6 Shared Socioeconomic Pathway (SSP) scenarios:
| Value | Pathway | Description |
| ---------- | -------------------------- | --------------------------------------------------------------- |
| `SSP1-2.6` | Sustainability | Strong mitigation; warming likely limited to \~1.5–2 °C by 2100 |
| `SSP2-4.5` | Middle of the road | Moderate mitigation; \~2–3 °C warming |
| `SSP3-7.0` | Regional rivalry | High emissions; \~3–4 °C warming (default) |
| `SSP5-8.5` | Fossil-fuelled development | Highest emissions; \~4–5 °C warming |
```bash theme={null}
curl "https://api.climatifai.com/agri/climate?lat=-34.6&lon=-58.4&from=1991&to=2020&scenario=SSP1-2.6"
```
For a risk-based analysis, you might run all four scenarios and compare the `projected` precipitation totals to understand the range of possible outcomes for your crop.
The `/agri/advisor` endpoint uses the same historical climate data internally. Calling `/agri/climate` first lets you inspect the raw inputs — annual precipitation, mean temperature, and soil moisture — before the advisor converts them into weighted factor scores.
For example, if the historical series shows average annual precipitation of 450 mm for a location where you plan to grow coffee (ideal: 1 200–2 200 mm), you can anticipate a low rainfall adequacy score before calling the advisor. This lets you validate that the climate data looks reasonable for your region before building an irrigation or crop-selection decision on top of it.
The `projected` series also reveals whether conditions are expected to improve or deteriorate under a given scenario, giving you a longer-term view for capital investment decisions.
The response includes a `_upstream_hints` object with `historical` and `projected` keys. If the Open-Meteo service returns an error for either dataset — for example, a temporary rate-limit or an unsupported coordinate — the corresponding hint field will contain the error message from upstream instead of being `null`. When you see a non-null hint, the returned data may be stale (served from cache) or partially missing.
```json theme={null}
"_upstream_hints": {
"historical": null,
"projected": "Open-Meteo climate API: model data not available for this coordinate"
}
```