# API Usage — Petrel Karst & Depressions Layer v0.1

Delivered through the Petrel API. Every download is authenticated.

## Authentication

1. Sign up at https://petreldata.io/signup (free tier available)
2. Generate an API key at https://petreldata.io/account#api-keys
3. Export it

```bash
# Petrel keys look like tlk.<uuid>.<secret> — copy yours from
# https://petreldata.io/account#api-keys
export PETREL_API_KEY=tlk.1a2b3c4d-5e6f-7890-abcd-ef1234567890.xxxxxxxx
```

The header is `X-API-Key`. There is no `Authorization: Bearer` form.

## Endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/v1/layer/karst_depressions` | GET | List available vintages |
| `/v1/layer/karst_depressions/v0.1_global_dem` | GET | Layer manifest (STAC item + docs) |
| `/v1/layer/karst_depressions/v0.1/bundle` | GET | Signed-URL manifest for the full download |

## Quotas

Your plan's monthly allowance is shared across the API; the authoritative
figures live at https://petreldata.io/pricing.

| Plan | Included lookups / month | Beyond the quota |
|---|---|---|
| Free | 1,000 | requests return HTTP 429 `quota_exceeded`; nothing is charged |
| Indie | 10,000 | overage billed per lookup if you enable it |
| Growth | 50,000 | overage billed per lookup if you enable it |
| Scale | 250,000 | overage billed per lookup if you enable it |

Overage is off until you turn it on (Account -> Billing). A short burst limit
also applies per key, so batch rather than firing parallel bursts.

## Download

```bash
# 1. Signed-URL manifest (URLs valid for 1 hour)
curl -s -H "X-API-Key: $PETREL_API_KEY" \
  https://api.petreldata.io/v1/layer/karst_depressions/v0.1/bundle > bundle.json

# 2. Pull both bands
for n in karst_depression_depth_90m.tif karst_solubility_90m.tif; do
    jq -r --arg n "$n" '.files[] | select(.name==$n) | .url' bundle.json \
      | xargs -r curl -s -o "$n"
done
```

## Reading the values

```python
import rasterio

with rasterio.open("karst_depression_depth_90m.tif") as src:
    raw = src.read(1)
    scale = float(src.tags().get("SCALE", src.tags(1).get("SCALE", 1.0)))
    depth_m = raw * scale          # metres below the sink-filled surface
```

Read `SCALE` from the tags; do not hard-code it. A value of 0 means the pixel
drains — it does **not** mean the ground is stable. See README.md.

## One thing to get right

`karst_depression_depth_90m.tif` is a **terrain measurement in metres**, not a
probability. If you need a ranking, use depth directly; if you need a
probability of collapse, this layer does not provide one and neither does any
global product we are aware of. See model_card.md for why.