Current version: v0.1.0
Tags: aclimate, climate, agriculture, python, sdk, api

AClimate SDK PY is an asynchronous Python client for consuming endpoints from the AClimate v3 API. It provides typed methods for authentication, countries, administrative regions, locations, historical climate data, climatology, agroclimatic indicators, GeoServer point data, and available periods.

The SDK is designed to be installed directly from GitHub and used by applications, APIs, notebooks, and LLM/RAG workflows that need structured access to AClimate climate and agroclimatic data.

This project is configured to work with uv for dependency management, virtual environments, locking, testing, and package installation.

Before installing the SDK, make sure you have:

• Python 3.10 or higher.
• uv installed.
• A valid AClimate API client ID and client secret, or an access token.

Install uv if needed:

pip install uv

Inside another uv project, add it as a dependency:

uv add git+https://github.com/CIAT-DAPA/aclimatesdkpy.git

Install directly from GitHub with uv:

uv pip install git+https://github.com/CIAT-DAPA/aclimatesdkpy.git

If you use uv add:

uv remove aclimatesdkpy

If you use uv pip install:

uv pip uninstall aclimatesdkpy

import asyncio
from aclimatesdkpy.aclimate_client import get_client

api_base_url = "https://api.aclimate.org/"
client_id = ""
client_secret = ""

client = await get_client(
        base_url=api_base_url,
        client_id=client_id,
        client_secret=client_secret,
    )

You can also use an existing bearer token:

import asyncio
from aclimatesdkpy import AClimateClient

async with AClimateClient(access_token="YOUR_ACCESS_TOKEN") as client:
    countries = await client.get_countries()

await client.get_client_token()
await client.validate_token()

The SDK automatically obtains and refreshes a client-credentials token when client_id and client_secret are configured.

Endpoints are included:

• Endpoints documented with location_id accept a single integer.
• Endpoints documented with location_ids or country_ids accept either a comma-separated string or a Python list such as [1, 2, 3].
• Date parameters accept YYYY-MM-DD strings or datetime.date objects.

countries = await client.get_countries_by_name("Colombia")

admin1 = await client.get_admin1_by_country_ids([1, 2, 3])

locations = await client.get_locations_by_country_ids_with_data(country_ids=[1], days=7)

records = await client.get_historical_daily_by_date_range_all_measures(
    location_ids=[101, 102],
    start_date="2025-05-01",
    end_date="2025-05-26",
)

The ContextBuilder can generate narrative context in English or Spanish. English is the default.

from aclimatesdkpy import ContextBuilder

# English output
builder = ContextBuilder(language="en")
text = builder.daily_climate_summary(records)
print(text)

# Spanish output
builder_es = ContextBuilder(language="es")
text_es = builder_es.daily_climate_summary(records)
print(text_es)

You can also switch the language in place:

builder.set_language("es")

Currently supported languages are:

aclimatesdkpy/
├── .python-version
├── pyproject.toml
├── uv.lock
├── README.md
├── src/
│   └── aclimatesdkpy/
│       ├── __init__.py
│       ├── aclimate_api_error.py
│       ├── aclimate_auth_error.py
│       ├── aclimate_client.py
│       ├── aclimate_models.py
│       ├── context_builder.py
│       └── utils.py
└── tests/
    └── test_client.py

For local development:

git clone https://github.com/CIAT-DAPA/aclimatesdkpy.git
cd aclimatesdkpy
uv venv

Create or update the virtual environment from the lockfile:

uv sync --all-extras --dev

Run commands inside the managed environment:

uv run python examples/basic_usage.py

Run tests:

uv run pytest

Run linting:

uv run ruff check .

Run static typing:

uv run mypy src

Build the package:

uv build

Update the lockfile after dependency changes:

uv lock

MIT License.