# API Usage — Petrel Ignition Density Layer v0.3

The Petrel Ignition Density Layer v0.3 is delivered through the Petrel API.
Every download is authenticated; downloads are rate-limited per account tier.

## Authentication

You need a Petrel account and an API key:

1. Sign up at https://petreldata.io/signup (free tier available)
2. Generate an API key under your account settings
3. Export it as `PETREL_API_KEY` in your shell environment

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

## Endpoints (v1 stable)

| Endpoint | Method | Description |
|---|---|---|
| `/v1/layer/ignition` | GET | List available ignition vintages |
| `/v1/layer/ignition/v0.3_global_ml` | GET | Layer manifest (STAC item + docs) |
| `/v1/layer/ignition/v0.3/bundle` | GET | Request signed URL for the full layer download (rate-limited) |

## 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 your requests rather than firing them in
parallel bursts.

## Code snippets

### curl — full bundle download

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

# 2. Download the 3 layer files
for f in anthro lightning total; do
    jq -r --arg n "ignition_density_${f}_0p05deg.tif" \
      '.files[] | select(.name==$n) | .url' bundle.json \
      | xargs -I{} curl -s "{}" -o ignition_density_${f}_0p05deg.tif
done
```

### Python — point query

At ~5 km per cell, a point query answers "what is the ignition propensity of
the landscape around this location":

```python
import os, requests, rasterio

api_key = os.environ["PETREL_API_KEY"]
r = requests.get(
    "https://api.petreldata.io/v1/layer/ignition/v0.3/bundle",
    headers={"X-API-Key": api_key},
).json()
urls = {f["name"]: f["url"] for f in r["files"]}   # 1-hour presigned URLs

lat, lon = 34.05, -118.24                      # Los Angeles
with rasterio.open(urls["ignition_density_total_0p05deg.tif"]) as src:
    raw = next(src.sample([(lon, lat)]))[0]
    scale = float(src.tags()["PETREL_SCALE"])
    if raw == src.nodata:
        print("no data (ocean / outside coverage)")
    else:
        print(f"total ignition propensity: {raw * scale:.3f} (relative, 0-1)")
```

### Python — windowed read over HTTPS

You don't need to download the full layer if you only want a region.
`rasterio` can stream-open a COG directly:

```python
import os, requests
import rasterio
from rasterio.windows import from_bounds

api_key = os.environ["PETREL_API_KEY"]
r = requests.get(
    "https://api.petreldata.io/v1/layer/ignition/v0.3/bundle",
    headers={"X-API-Key": api_key},
).json()
urls = {f["name"]: f["url"] for f in r["files"]}   # 1-hour presigned URLs

# Lightning ignition density over the Mediterranean
with rasterio.open(urls["ignition_density_lightning_0p05deg.tif"]) as src:
    win = from_bounds(-10, 30, 25, 47, transform=src.transform)
    raw = src.read(1, window=win)
    scale = float(src.tags()["PETREL_SCALE"])
    events_per_km2_yr = raw * scale            # physical; 65535*scale = NoData
```

### R — windowed read (using `terra`)

```r
library(terra)
api_key <- Sys.getenv("PETREL_API_KEY")
manifest <- httr::GET(
    "https://api.petreldata.io/v1/layer/ignition/v0.3/bundle",
    httr::add_headers(`X-API-Key` = api_key)
)
files <- httr::content(manifest)$files
url <- Filter(function(f) f$name == "ignition_density_total_0p05deg.tif", files)[[1]]$url

r <- rast(url)
med <- crop(r, ext(-10, 25, 30, 47))
plot(med)
```

### QGIS / ArcGIS

For desktop GIS use:

1. Download via the bundle endpoint (Petrel API key required)
2. Open the `.tif` directly in QGIS/ArcGIS — internal tiling and overviews
   are honored
3. The STAC item (`/v1/layer/ignition/v0.3_global_ml` → STAC JSON) can be
   used with STAC plugins for automated discovery

## Layer encoding reference

All three layers are uint16 with a linear scale factor recorded in the
`PETREL_SCALE` file tag — multiply the raw integer by it to get physical
values (`physical = raw × PETREL_SCALE`):

| File | PETREL_SCALE | Physical unit / range |
|---|---|---|
| `ignition_density_anthro_0p05deg.tif` | ≈ 1.526 × 10⁻⁵ | P(fire \| human context), 0–1 |
| `ignition_density_lightning_0p05deg.tif` | ≈ 1.526 × 10⁻⁵ | relative index, 0–1 |
| `ignition_density_total_0p05deg.tif` | ≈ 1.526 × 10⁻⁵ | relative propensity, 0–1 |

Always read the scale from the file tag rather than hard-coding it. NoData
sentinel: `65535` (ocean, Antarctica, unscored cells).

**Interpretation reminder:** `total` is a **relative** ignition propensity in
[0,1] — a spatial ranking, not "ignitions per year". The `lightning`
sub-layer is likewise a relative index, not a rate (it was mislabelled as
one through v0.2 — see RELEASE_NOTES.md). Native resolution is ~5 km (0.05°); do not
treat resampled derivatives as adding information.

## Errors and rate-limit behavior

The API returns standard HTTP status codes:

- `401 Unauthorized` — missing or invalid API key
- `403 Forbidden` — license tier doesn't permit this endpoint
- `429 Too Many Requests` — rate limit exceeded; response includes
  `Retry-After` header and `X-RateLimit-Reset` timestamp
- `404 Not Found` — vintage or layer not recognized
- `503 Service Unavailable` — temporary backend issue; safe to retry
  with exponential backoff

## Support

- **Documentation:** https://petreldata.io/docs/layers/ignition
- **API status:** https://status.petreldata.io
- **Bugs / questions:** layers@petreldata.io
- **Commercial inquiries:** licensing via https://petreldata.io/demo