Skip to content

Getting started

No local setup? Use Colab

Open In Colab — follow this whole page interactively in the companion notebook: install, first fetch, and the optional Earth Engine setup, all in the browser.

1. Install

Straight from GitHub, no clone needed:

pip install "git+https://github.com/CGIAR-Climate-Data-Hub/climate-toolkit.git"

From a Jupyter notebook, prefix with %:

%pip install "git+https://github.com/CGIAR-Climate-Data-Hub/climate-toolkit.git"

For development, clone and use uv:

git clone https://github.com/CGIAR-Climate-Data-Hub/climate-toolkit.git
cd climate-toolkit
uv sync

2. Google Earth Engine credentials

Most gridded sources (agera_5, era_5, chirps_v3_daily_rnl, nex_gddp) are served through Google Earth Engine. nasa_power and the weather-station sources (ghcn_daily, gsod) need no credentials at all.

This can be completely free

Earth Engine is free for noncommercial use (research, academia, nonprofit, education). When registering at code.earthengine.google.com/register choose:

  • "Register a Noncommercial or Commercial Cloud project"
  • Usage type: Unpaid usage (do NOT pick "Paid usage")
  • Category: e.g. Academia & Research or Nonprofit

No billing account or credit card is required for this path.

Setup steps:

  1. Sign up at earthengine.google.com and register a Cloud project (see tip above).
  2. Authenticate once on your machine:
earthengine authenticate
  1. Tell the toolkit which Cloud project to use. Any one of GCP_PROJECT_ID, GOOGLE_CLOUD_PROJECT, or EE_PROJECT_ID works:
# macOS / Linux
export GCP_PROJECT_ID=your-ee-project-id

# Windows PowerShell
$env:GCP_PROJECT_ID = "your-ee-project-id"
  1. Verify the setup:
climate-toolkit-gee-check

3. First analysis

import climate_toolkit as ct
from datetime import date

# Daily data — no credentials needed for nasa_power
df = ct.fetch_climate_data(
    source="nasa_power",
    location_coord=(-1.286, 36.817),
    date_from=date(2020, 1, 1),
    date_to=date(2020, 12, 31),
)

# Crop hazards for a season (uses Earth Engine sources by default)
hazards = ct.evaluate_hazards(
    crop_name="maize",
    location_coord=(-1.286, 36.817),
    date_from="2020-01-01",
    date_to="2020-12-31",
)

Getting help

Every public function has full parameter documentation:

help(ct)                        # package overview
help(ct.fetch_climate_data)     # any function

In Jupyter/IPython: ct.fetch_climate_data?. In VSCode: hover over the function name.