# Bulk Download Instructions — Petrel Ignition Density Layer v0.3

This document covers downloading the full layer bundle. Because the product
is native ~5 km (0.05°), the entire bundle is only **~35 MB** — unlike the
multi-gigabyte 90 m Petrel layers, just downloading everything is the
sensible default. For windowed / regional access, see
[`API_USAGE.md`](API_USAGE.md).

## What's in a full bundle (~35 MB)

```
ignition_density_anthro_0p05deg.tif        ~11 MB
ignition_density_lightning_0p05deg.tif      ~6 MB
ignition_density_total_0p05deg.tif         ~13 MB
ignition_density_anthro_global.png         ~0.8 MB
ignition_density_lightning_global.png      ~0.6 MB
ignition_density_total_global.png          ~0.6 MB
ignition_layers_composite.png              ~1.1 MB
README.md                                   ~6 KB
methodology.md                              ~8 KB
model_card.md                               ~7 KB
data_sources.md                             ~5 KB
validation_report.md                        ~7 KB
RELEASE_NOTES.md                            ~1 KB
LICENSE.md                                  ~1 KB
CITATION.cff                                ~1 KB
API_USAGE.md                                ~5 KB
bulk_download_instructions.md               ~3 KB
ignition_v0.3_global_ml_stac_item.json      ~6 KB
```

## Two ways to bulk-download

### 1. via Petrel API (recommended)

`$PETREL_API_KEY` is your Petrel API key (`tlk.…`) from the dashboard —
the free tier works. The bundle endpoint returns a JSON manifest with a
1-hour presigned URL for every file in the bundle.

```bash
# Fetch the signed-URL manifest:
curl -s -H "X-API-Key: $PETREL_API_KEY" \
  https://api.petreldata.io/v1/layer/ignition/v0.3/bundle > bundle.json

# Download everything (~34 MB total):
mkdir -p ignition_v0.3
jq -r '.files[] | [.url, .name] | @tsv' bundle.json | \
  while IFS=$'\t' read -r url name; do
    curl -s "$url" -o "ignition_v0.3/$name"
  done
```

The URLs expire after 1 hour (`expires_at` in the response) — re-request
the manifest if a long download outlives them.

### 2. via direct S3 (for internal automation only)

If you have a Petrel staff role with direct bucket access:

```bash
aws s3 sync s3://petrel-data/layers/ignition/v0.3_global_ml/ ./ignition_v0.3/
```

This skips the API rate-limit but requires explicit IAM access. Most users
should go through the API.

## Bandwidth and rate limit notes

- The full bundle is ~35 MB — a few seconds on most connections. Free-tier
  accounts can download it up to **10 times per day**.
- Each bundle download is signed for **1 hour** from the moment the API call
  returns. If a URL expires, request a fresh one with another API call.
- For automated use (CI / production pipelines), cache the bundle locally —
  there is no reason to re-download more than once per vintage release.

## Verifying integrity

Each file has an MD5 checksum recorded in the STAC item under the
`assets.<name>.checksum` field. To verify after download:

```bash
# Read expected from STAC item
EXPECTED=$(jq -r '.assets.ignition_density_total.checksum' ignition_v0.3_global_ml_stac_item.json)
# Compute actual
ACTUAL=$(md5sum ignition_density_total_0p05deg.tif | awk '{print $1}')
[ "$EXPECTED" == "$ACTUAL" ] && echo "OK" || echo "FAIL"
```

(MD5s are populated at S3 push time and recorded in the STAC item.)

## Licensing reminder

Bulk download is restricted to **non-commercial use** under CC-BY-NC-4.0.
By downloading, you accept the license terms in [`LICENSE.md`](LICENSE.md).

For commercial bundling, redistribution, or incorporation into paid
products / services / analyses, request a commercial license at
**licensing via https://petreldata.io/demo** before downloading.