Metadata-Version: 2.5
Name: terrakio-api
Version: 0.13.0
Summary: Client version of the terrakio-python-api
Requires-Python: >=3.11
Requires-Dist: terrakio-core==0.13.0
Description-Content-Type: text/markdown

# 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

```bash
pip install terrakio-api
```

## Signing in

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

```python
from terrakio_api import Client

client = Client()  # defaults to https://dev-omni.terrak.io (fronts all regions)
# or name an environment: Client(env="prod" | "candidate" | "dev-au" | "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

```python
# 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

```python
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.

```python
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](https://github.com/HaizeaAnalytics/terrakio-python-api).
