# Bulk Download Instructions — Petrel Fuel Layer v1.0 Global FM40 Crosswalk

This document covers downloading the full layer bundle. v1.0 ships a **single**
raster — the FM40 class — plus the preview and docs, so "download everything" is
the sensible default. For windowed / regional access, see
[`API_USAGE.md`](API_USAGE.md).

## What's in a full bundle

```
fuel_model_class_270m.tif                     the class raster (bulk of the download)
fuel_model_class_global.png                   ~1 MB   global preview
README.md                                      ~7 KB
methodology.md                                 ~8 KB
model_card.md                                  ~7 KB
data_sources.md                                ~5 KB
validation_report.md                           ~6 KB
RELEASE_NOTES.md                               ~1 KB
LICENSE.md                                     ~2 KB
CITATION.cff                                   ~1 KB
API_USAGE.md                                   ~6 KB
bulk_download_instructions.md                  ~3 KB
fuel_v1.0_global_crosswalk_stac_item.json      ~6 KB
```

The class raster is a global ~270 m categorical uint8 COG (DEFLATE, land only) —
on the order of a few hundred MB, well under the multi-gigabyte 90 m Petrel
hazard products. The **exact** file size is recorded in the STAC item's
`assets.fuel_model_class.file:size` field.

## 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/fuel/v1.0/bundle > bundle.json

# Download everything:
mkdir -p fuel_v1.0
jq -r '.files[] | [.url, .name] | @tsv' bundle.json | \
  while IFS=$'\t' read -r url name; do
    curl -s "$url" -o "fuel_v1.0/$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/fuel/v1.0_global_crosswalk/ ./fuel_v1.0/
```

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

## Bandwidth and rate limit notes

- The class raster is a few hundred MB — a short download on most connections,
  but larger than the ~5 km / ~28 km Petrel layers. Free-tier accounts can pull
  the bundle 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 raster 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.fuel_model_class.checksum' fuel_v1.0_global_crosswalk_stac_item.json)
ACTUAL=$(md5sum fuel_model_class_270m.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

This Layer is **CC-BY-4.0** — you may use, adapt, and redistribute it **for any
purpose, including commercially**, provided you attribute Petrel **and** the two
upstream sources. Include, in a reasonable place for your medium:

```
Petrel Fuel Layer v1.0 (Global FM40 Crosswalk), CC-BY-4.0.
Derived from © ESA WorldCover 2021 and Beck et al. (2018) Köppen-Geiger.
```

No separate commercial license is required for the data. See
[`LICENSE.md`](LICENSE.md) for the full statement. (Higher-volume *API* access is
a service tier, separate from the data license — see
[`API_USAGE.md`](API_USAGE.md).)