Getting started

Get started with Cecil in a few steps.

Sign up

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)"

Install 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

Create an AOI

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)

Acquire a dataset

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

import cecil

client = cecil.Client()

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

print(subscription)

Analyse your dataset

Install matplotlib for data visualisation.

pip install matplotlib

Visualise forest loss over time. You may get an empty dataset when you call load_xarray() which means the previous step is still processing. Please wait for provider processing accordingly.

import cecil
import matplotlib.pyplot as plt

client = cecil.Client()

ds = client.load_xarray("my-subscription-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()