# Bulk Download Instructions — Petrel Aridity Index Layer v0.1

This document covers downloading the full layer bundle. Because the product is
native ~28 km (0.25°), the entire bundle is only a **few 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 (~few MB)

```
aridity_index_0p25deg.tif             ~0.7 MB
aridity_class_0p25deg.tif             ~0.1 MB
aridity_index_ci_0p25deg.tif          ~0.6 MB
aridity_index_0p25deg_global.png      ~0.7 MB
README.md                              ~6 KB
methodology.md                         ~7 KB
model_card.md                          ~6 KB
data_sources.md                        ~4 KB
validation_report.md                   ~6 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
aridity_v0.1_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.

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

# Download everything:
mkdir -p aridity_v0.1
jq -r '.files[] | [.url, .name] | @tsv' bundle.json | \
  while IFS=$'\t' read -r url name; do
    curl -s "$url" -o "aridity_v0.1/$name"
  done
```

Or with HTTPS curl (works without the AWS CLI):

```bash
URL=$(...)  # as above
for f in index class index_ci; do
    curl -O ${URL}/aridity_${f}_0p25deg.tif
done
curl -O ${URL}/aridity_index_0p25deg_global.png
for doc in README methodology model_card data_sources validation_report \
           RELEASE_NOTES LICENSE API_USAGE bulk_download_instructions; do
    curl -O ${URL}/${doc}.md
done
curl -O ${URL}/CITATION.cff
curl -O ${URL}/aridity_v0.1_global_ml_stac_item.json
```

### 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/aridity/v0.1_global_ml/ ./aridity_v0.1/
```

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 a few MB — a second or two 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
EXPECTED=$(jq -r '.assets.aridity_index.checksum' aridity_v0.1_global_ml_stac_item.json)
ACTUAL=$(md5sum aridity_index_0p25deg.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.