> ## 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.

# GET /agri/climate — Climate series and projections

> Retrieve monthly historical climate data and CMIP6 future projections for any LATAM location, including temperature, precipitation, and soil moisture.

The climate endpoint returns two time series for a geographic location: a historical monthly record spanning the years you specify, and a CMIP6 climate projection under a chosen emissions scenario. Both series include temperature, precipitation, and soil moisture for each month. You can use this data to analyse long-term climate trends, calibrate crop models, or compare a baseline period against projected future conditions.

## Endpoint

```text theme={null}
GET api.climatifai.com/agri/climate
```

## Parameters

<ParamField query="lat" type="float" required>
  Latitude of the location in decimal degrees, WGS 84.
</ParamField>

<ParamField query="lon" type="float" required>
  Longitude of the location in decimal degrees, WGS 84.
</ParamField>

<ParamField query="from" default="1991" type="integer">
  Start year (inclusive) for the historical data series. Combined with `to`, this defines the historical baseline period.
</ParamField>

<ParamField query="to" default="2020" type="integer">
  End year (inclusive) for the historical data series.
</ParamField>

<ParamField query="scenario" default="SSP3-7.0" type="string">
  CMIP6 emissions scenario to use for the projected series. Example values: `SSP1-2.6`, `SSP2-4.5`, `SSP3-7.0`, `SSP5-8.5`.
</ParamField>

<ParamField query="country_iso" type="string">
  Optional ISO 3166-1 alpha-2 country code for the location being queried. Must be a LATAM country code, excluding Brazil (`BR`). Examples: `PE`, `MX`, `CO`. Safe to omit for standard use.
</ParamField>

## Response

<ResponseField name="lat" type="float" required>
  Latitude echoed from the request.
</ResponseField>

<ResponseField name="lon" type="float" required>
  Longitude echoed from the request.
</ResponseField>

<ResponseField name="scenario" type="string" required>
  CMIP6 scenario used for the projected series, echoed from the request.
</ResponseField>

<ResponseField name="historical" type="array" required>
  Monthly climate observations for the requested historical period. Each element is a `ClimateMonth` object.

  <Expandable title="ClimateMonth properties">
    <ResponseField name="year" type="integer">
      Calendar year of this record.
    </ResponseField>

    <ResponseField name="month" type="integer">
      Calendar month (1–12) of this record.
    </ResponseField>

    <ResponseField name="temp_c" type="float">
      Mean air temperature in degrees Celsius for this month.
    </ResponseField>

    <ResponseField name="precip_mm" type="float">
      Total precipitation in millimetres for this month.
    </ResponseField>

    <ResponseField name="soil_moisture" type="float">
      Volumetric soil moisture in m³/m³. May be `null` if unavailable for the period.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="projected" type="array" required>
  Monthly climate values from the CMIP6 projection. Shares the same `ClimateMonth` structure as `historical`.
</ResponseField>

<ResponseField name="_cache" type="object">
  Cache freshness metadata for both the historical and projected datasets.

  <Expandable title="_cache properties">
    <ResponseField name="historical" type="object">
      Cache metadata for the historical series. Contains `cached_at` (ISO 8601 string) and `stale` (boolean).
    </ResponseField>

    <ResponseField name="projected" type="object">
      Cache metadata for the projected series. Contains `cached_at` (ISO 8601 string) and `stale` (boolean).
    </ResponseField>

    <ResponseField name="any_stale" type="boolean">
      `true` if either the historical or projected cache entry is stale.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="_upstream_hints" type="object">
  Contains upstream error information if any part of the data could not be fetched live and a stale or fallback result was served instead.

  <Expandable title="_upstream_hints properties">
    <ResponseField name="historical" type="string">
      Error message from the Open-Meteo historical endpoint, if any. `null` when no error occurred.
    </ResponseField>

    <ResponseField name="projected" type="string">
      Error message from the Open-Meteo projection endpoint, if any. `null` when no error occurred.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error codes

| Code  | Description                                                                     |
| ----- | ------------------------------------------------------------------------------- |
| `502` | Upstream error from Open-Meteo. The detail field contains the original message. |
| `503` | Open-Meteo rate limit exceeded. Retry after a short back-off.                   |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.climatifai.com/agri/climate?lat=4.711&lon=-74.0721&from=1991&to=2020&scenario=SSP3-7.0&country_iso=CO"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "lat": 4.711,
    "lon": -74.0721,
    "scenario": "SSP3-7.0",
    "historical": [
      {
        "year": 1991,
        "month": 1,
        "temp_c": 13.8,
        "precip_mm": 42.1,
        "soil_moisture": 0.198
      },
      {
        "year": 1991,
        "month": 2,
        "temp_c": 14.2,
        "precip_mm": 58.4,
        "soil_moisture": 0.213
      }
    ],
    "projected": [
      {
        "year": 2041,
        "month": 1,
        "temp_c": 15.1,
        "precip_mm": 38.7,
        "soil_moisture": 0.181
      },
      {
        "year": 2041,
        "month": 2,
        "temp_c": 15.6,
        "precip_mm": 52.0,
        "soil_moisture": 0.195
      }
    ],
    "_cache": {
      "historical": {
        "cached_at": "2026-05-18T08:30:00Z",
        "stale": false
      },
      "projected": {
        "cached_at": "2026-05-18T08:30:00Z",
        "stale": false
      },
      "any_stale": false
    },
    "_upstream_hints": {
      "historical": null,
      "projected": null
    }
  }
  ```
</ResponseExample>