Get started with Cecil in a few steps.

1. Sign up for an account

Run the following command in your terminal and follow the prompt. You will receive an email with instructions to generate your API key. By signing up, you agree to our Dataset Pricing and Terms.

/bin/bash -c "$(curl -fsSL <https://cecil.earth/sign-up.sh>)"

2. Install and configure the SDK

Install the SDK in your project virtual environment. Python ≥ 3.10 is required.

pip install cecil

Configure the SDK by setting the CECIL_API_KEY environment variable. Make sure to store your API key in an encrypted vault or secrets manager. Never store API keys in code or plain/text files.

# Linux and macOS
export CECIL_API_KEY="my-api-key"

# Windows
set CECIL_API_KEY=my-api-key

3. Create an area of interest

Create an area of interest (AOI) using the geometry object of a GeoJSON in EPSG:4326 coordinate reference system (CRS). Learn more about the AOI specification in the SDK.

import cecil

client = cecil.Client()

aoi = client.create_aoi(
		external_ref="Chaco Region",
    geometry={
        "type": "Polygon",
        "coordinates": [
            [
								[-60.530404375, -20.809574274],
								[-60.530404375, -21.173552046],
								[-59.99196906, -21.173552046],
								[-59.99196906, -20.809574274],
								[-60.530404375, -20.809574274],
            ]
        ]
    }
)

print(aoi)

4. Acquire a dataset for your AOI

Create a data request for your AOI using a dataset_id from our available datasets. This step runs in the background and may take from minutes to days depending on the data provider.

import cecil

client = cecil.Client()

hansen_global_forest_change = client.create_data_request(
		external_ref="Hansen Global Forest Change - Chaco Region",
    aoi_id="my-aoi-id",
    dataset_id="9659ec1d-7091-4f8b-9db5-e9fe07d2f508",
)

print(hansen_global_forest_change)

5. Analyse your dataset

Install matplotlib for data visualisation.

pip install matplotlib

Visualise forest loss over time.

import cecil
import matplotlib.pyplot as plt

client = cecil.Client()

ds = client.load_xarray('my-data-request-id')

# Pixel values above 0 indicate forest loss years.
forest_loss = ds['loss_year'].where(ds['loss_year'] > 0)

# Convert values from 1-24 to 2001-2024.
forest_loss_years = forest_loss + 2000

forest_loss_years.plot(cmap='plasma').colorbar.set_ticks(
    [2001, 2005, 2010, 2015, 2020, 2024]
)

plt.gca().set_title('Hansen Global Forest Change - Chaco Region')
plt.gca().set_aspect('equal')
plt.gca().set_facecolor('#101010')

plt.show()