Terrakio API Client

A Python client for Terrakio API. This package provides a user-friendly interface for accessing Terrakio's data services.

Features

• Authentication
• WCS queries and data retrieval
• Mass stats related functionalities
• Groups and dataset sharing

Installation

pip install terrakio-api

Signing in

People log in; machines carry a key. Either credential works on every route.

from terrakio_api import Client

client = Client()  # defaults to https://api-candidate.terrak.io (fronts all regions)
# or name an environment: Client(env="prod" | "candidate" | "dev" | "local" | …),
# settable for a whole session with TERRAKIO_ENV

# A person: stores a session that renews itself, so this is a one-off.
client.auth.login(email="XXX", password="XXX")

# A service account or CI job: an API key, from the argument or TERRAKIO_API_KEY.
client = Client(api_key="tk_...")

An API key takes precedence over a session: TERRAKIO_API_KEY, then a stored key, then the stored session. client.auth.view_api_key() is deprecated — it only ever returns the legacy key, which accounts created since named keys landed do not have.

API keys

# Create a key (the full key is returned only here, so store it now)
new_key = client.keys.create_key(label="my laptop")
print(new_key["key"])

# List your keys (metadata only) and revoke one
for key in client.keys.list_keys():
    print(key["id"], key["prefix"], key["label"])
client.keys.revoke_key(key_id=new_key["id"])

To rotate a key: create a new one, switch your code over to it, then revoke the old one.

Querying

from shapely.geometry import Point

dataset = client.geoquery(
    expr="prec=MSWX.precipitation@(year=2024, month=1)\nprec",
    feature=Point(149.057, -35.1548),
    output="netcdf",
)

Groups and sharing

A group is a set of people you grant datasets to, rather than naming each person on each dataset.

group = client.groups.create_group(name="the-team")
client.groups.add_user_to_group(group=group["id"], emails=["colleague@example.com"])

# Grant a dataset to the group, or share it with one person
client.groups.add_group_to_dataset(dataset="Rainfall", id=group["id"])
client.groups.add_user_to_dataset(dataset="Rainfall", emails=["colleague@example.com"])

# See who reaches it: access level, groups (a null name is a deleted group), people
client.groups.get_dataset_access(dataset="Rainfall")

client.groups.list_groups()              # groups you own
client.groups.list_groups(member=True)   # plus the ones you belong to

For more documentation, see the main repository.