🔥 landpyre

Discover & Download USGS LANDFIRE Data

Unofficial CLI and SDK for LANDFIRE data — discover, filter, search, and download geospatial datasets with ease.

Documentation · GitHub · Issues

Overview

landpyre is a modern, typed SDK and CLI for working with LANDFIRE geospatial datasets published by the USGS. It handles catalog discovery, fuzzy search, manifest-based reproducible downloads, checksum verification, and data export — all from the terminal or Python.

Built with Pydantic, Click, and Rich.

What's new in v0.2.0

Typed SDK — LandpyreClient with search(), download(), verify(), export()
Pydantic models — CatalogItem, CatalogFilter, DownloadResult, and more
landpyre search — fuzzy full-text search ranked by relevance
landpyre manifest — save reproducible download selections to manifest.json
landpyre verify — checksum and existence validation against a manifest
landpyre config — persistent defaults (default_region, default_output, etc.)
landpyre doctor — environment diagnostics (Python, disk, network, SSL, cache)
--dry-run on download — preview files and total size without hitting the network
--open on download — open the output folder in your file explorer after completion
--json on every command — machine-readable output for scripting
Schema versioning — stale caches are detected and prompt a helpful refresh
Resumable downloads — partial ZIPs are continued from where they left off
Checksum verification — MD5 verified during download when available

Installation

# Standard install
pip install landpyre

# With Parquet export support
pip install "landpyre[parquet]"

# From source (development)
git clone https://github.com/samapriya/landpyre.git
cd landpyre
pip install -e ".[dev]"

Requirements: Python ≥ 3.10, internet access for refresh (all other commands work offline).

CLI Quick Start

# 1. Fetch and cache the full LANDFIRE catalogue
landpyre refresh

# 2. Fuzzy-search the catalogue
landpyre search "hawaii fuel 2022"

# 3. Browse with filters
landpyre list --version "LF 2022" --region Hawaii

# 4. Statistics summary
landpyre stats

# 5. Save a manifest for reproducible downloads
landpyre manifest --version "LF 2022" --region Hawaii -o hawaii.json

# 6. Preview what will be downloaded (no network I/O)
landpyre download --manifest hawaii.json --dry-run

# 7. Download
landpyre download --manifest hawaii.json --output ./hawaii_data

# 8. Verify integrity
landpyre verify --manifest hawaii.json --output ./hawaii_data

# 9. Check your environment
landpyre doctor

SDK Quick Start

1. Setup & Client Exploration

from landpyre import LandpyreClient

client = LandpyreClient()

# refresh() is a no-op if a valid cache already exists.
# Pass force=True to always re-scrape.
snapshot = client.refresh()

print(f"Cache contains {snapshot.item_count} items.")
print(f"Last scraped: {snapshot.last_run}")
print(f"Schema version: {snapshot.schema_version}")

2. Filtering & Fuzzy Search

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter, FilterMode

client = LandpyreClient()
client.refresh()

# Precise regex filtering
f_regex = CatalogFilter(version=r"LF 202[234]", mode=FilterMode.REGEX)
items = client.get_items(f_regex)

# Ranked fuzzy search across product, theme, region, and version
results = client.search("hawaii fuel 2022", threshold=0.6)

for r in results[:3]:
    print(f"{r.score:.0%} - {r.item.filename}")

3. Manifests & Dry-runs

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter

client = LandpyreClient()
client.refresh()

items = client.get_items(CatalogFilter(region="Hawaii", version="LF 2022"))

# Save state to manifest
manifest = client.save_manifest(items, path="hawaii_lf2022.json")

# Dry run to calculate total payload
summary = client.dry_run(items, output_dir="./data")
print(f"Files to download : {summary['item_count']}")
print(f"Total size        : {summary['total_bytes_fmt']}")

# Load state back later
loaded = client.load_manifest("hawaii_lf2022.json")

4. Downloads & Verification

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter

client = LandpyreClient()
client.refresh()

items = client.get_items(CatalogFilter(region="Hawaii", version="LF 2022"))
client.save_manifest(items, path="hawaii_lf2022.json")

# Resumable multi-threaded download
results = client.download(items, output_dir="./data", workers=4)

# Post-download integrity verification against the manifest
vr = client.verify("hawaii_lf2022.json", output_dir="./data")

print(f"All OK        : {vr.all_ok}")
print(f"Files missing : {vr.files_missing}")
print(f"Files corrupt : {vr.files_corrupt}")

5. Exporting Catalog Metadata

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter

client = LandpyreClient()
client.refresh()

items = client.get_items(CatalogFilter(version="LF 2022"))

# Standard exports
client.export(items, format="json",     path="lf2022.json")
client.export(items, format="csv",      path="lf2022.csv")
client.export(items, format="markdown", path="lf2022.md")

# Parquet (requires `pip install "landpyre[parquet]"`)
client.export(items, format="parquet",  path="lf2022.parquet")

CLI Reference

`landpyre refresh`

Scrapes the LANDFIRE catalogue and saves it to ~/.landpyre/landfire_latest.json.

landpyre refresh                  # Refresh only if no valid cache exists
landpyre refresh --force          # Force re-scrape
landpyre refresh --check-scraper  # Health-check the scraper without saving
landpyre refresh --json           # Machine-readable output

`landpyre search QUERY`

Fuzzy full-text search across product, theme, region, and version. Results are ranked by relevance score.

landpyre search "hawaii fuel"
landpyre search "CONUS LF 2022" --limit 10
landpyre search "fire behavior" --threshold 0.5
landpyre search "fuel model" --json

Flag	Description
`--limit` / `-l`	Maximum results (default: 20)
`--threshold`	Minimum relevance score 0.0–1.0 (default: 0.0)
`--json`	Output as JSON

`landpyre list`

Browse the catalogue with exact/substring filters.

landpyre list
landpyre list --version "LF 2022"
landpyre list --region "Hawaii" --version "LF 2022"
landpyre list --theme "Fire" --limit 20 --url
landpyre list --region "CONUS" --json

Flag	Short	Description
`--version`	`-V`	Filter by version
`--region`	`-r`	Filter by region
`--theme`	`-t`	Filter by theme
`--limit`	`-l`	Max rows (default: 50)
`--url`		Show download URLs
`--json`		Output as JSON

`landpyre manifest`

Save a filtered selection to a portable manifest.json.

landpyre manifest --version "LF 2022" --region Hawaii
landpyre manifest --version "LF 2024" -o conus_2024.json
landpyre manifest --show manifest.json        # Inspect an existing manifest

Flag	Short	Description
`--version`	`-V`	Version filter
`--region`	`-r`	Region filter
`--theme`	`-t`	Theme filter
`--output`	`-o`	Destination path (default: `manifest.json`)
`--show`	`-s`	Inspect an existing manifest
`--json`		Output as JSON

`landpyre download`

Download files and extract TIF data. Accepts filters or a manifest.

landpyre download --version "LF 2022" --output lf2022
landpyre download --manifest manifest.json --output ./data
landpyre download --region "CONUS" --dry-run          # Preview only
landpyre download --manifest hawaii.json --yes --open # Skip confirm, open folder

Flag	Short	Default	Description
`--version`	`-V`		Version filter
`--region`	`-r`		Region filter
`--theme`	`-t`		Theme filter
`--manifest`	`-m`		Replay a manifest.json
`--output`	`-o`	config / `landfire_output`	Output directory
`--workers`	`-w`	config / `4`	Concurrent threads
`--yes`	`-y`		Skip confirmation
`--dry-run`			Preview without downloading
`--open`			Open output folder after download
`--json`			Output as JSON

`landpyre verify`

Verify downloaded files against a manifest (existence, size, MD5 checksum).

landpyre verify
landpyre verify --manifest hawaii.json --output ./hawaii_data
landpyre verify --json

`landpyre config`

View and modify persistent configuration stored at ~/.config/landpyre/config.toml.

landpyre config show
landpyre config get default_region
landpyre config set default_region CONUS
landpyre config set default_workers 6
landpyre config set auto_confirm true

Key	Default	Description
`default_output`	`landfire_output`	Default download directory
`default_workers`	`4`	Default concurrent threads
`default_region`	—	Default region filter
`default_version`	—	Default version filter
`default_theme`	—	Default theme filter
`cache_dir`	`~/.landpyre`	Override cache location
`log_level`	`WARNING`	Logging level
`auto_confirm`	`false`	Skip download confirmation
`no_color`	`false`	Disable colour output

`landpyre doctor`

Run environment diagnostics: Python version, disk space, network reachability, SSL/TLS, cache existence, directory permissions, config validity, ZIP support, and Pydantic installation.

landpyre doctor
landpyre doctor --json

SDK Reference

`LandpyreClient`

from landpyre import LandpyreClient

client = LandpyreClient(
    cache_dir=None,   # override cache location
    workers=4,        # default download thread count
)

Method	Returns	Description
`refresh(force, progress_callback)`	`CatalogSnapshot`	Scrape and cache
`get_snapshot()`	`CatalogSnapshot`	Load current cache
`get_items(f)`	`list[CatalogItem]`	Filter query
`search(query, limit, threshold, f)`	`list[SearchResult]`	Fuzzy search
`save_manifest(items, path)`	`Manifest`	Save manifest
`load_manifest(path)`	`Manifest`	Load manifest
`items_from_manifest(manifest)`	`list[CatalogItem]`	Convert for download
`download(items, output_dir, workers, dry_run)`	`list[DownloadResult]`	Download
`download_manifest(path, output_dir, ...)`	`list[DownloadResult]`	Load + download
`dry_run(items, output_dir)`	`dict`	Preview summary
`verify(manifest, output_dir)`	`ValidationResult`	Integrity check
`export(items, format, path)`	`Path`	Export to file

Key Models

from landpyre.models import (
    CatalogItem,      # One downloadable entry
    CatalogFilter,    # Filter criteria (substring/exact/regex/fuzzy)
    CatalogSnapshot,  # The full cached catalogue
    DownloadResult,   # Outcome of one download
    Manifest,         # Portable manifest document
    ValidationResult, # Outcome of a verify run
    LandpyreConfig,   # User preferences
)

Filtering Logic

All filters are case-insensitive and ANDed together.

from landpyre.models import CatalogFilter, FilterMode

CatalogFilter(region="haw")                                    # Substring (default)
CatalogFilter(region="Hawaii", mode=FilterMode.EXACT)          # Exact
CatalogFilter(version=r"LF 202[234]", mode=FilterMode.REGEX)   # Regex
CatalogFilter(product="fbfm", mode=FilterMode.FUZZY, fuzzy_threshold=0.5)  # Fuzzy

Output Structure

landfire_output/
└── tif/
    ├── LF2022_FBFM40_220_HI.tif
    ├── LF2022_FVH_220_HI.tif
    └── ...

ZIP files are downloaded to .tmp_zips/, TIFs are extracted flat into tif/, and the ZIPs are removed automatically.

Links

Documentation: landpyre.geocarpentry.org
GitHub: github.com/samapriya/landpyre
PyPI: pypi.org/project/landpyre
Issues: github.com/samapriya/landpyre/issues

Apache 2.0 License · Built by Samapriya Roy · Powered by Pydantic, Click, and Rich

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
landpyre		landpyre
tests		tests
.gitignore		.gitignore
CNAME		CNAME
LICENSE		LICENSE
README.md		README.md
index.html		index.html
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

🔥 landpyre

Overview

What's new in v0.2.0

Installation

CLI Quick Start

SDK Quick Start

1. Setup & Client Exploration

2. Filtering & Fuzzy Search

3. Manifests & Dry-runs

4. Downloads & Verification

5. Exporting Catalog Metadata

CLI Reference

`landpyre refresh`

`landpyre search QUERY`

`landpyre list`

`landpyre manifest`

`landpyre download`

`landpyre verify`

`landpyre config`

`landpyre doctor`

SDK Reference

`LandpyreClient`

Key Models

Filtering Logic

Output Structure

Links

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🔥 landpyre

Overview

What's new in v0.2.0

Installation

CLI Quick Start

SDK Quick Start

1. Setup & Client Exploration

2. Filtering & Fuzzy Search

3. Manifests & Dry-runs

4. Downloads & Verification

5. Exporting Catalog Metadata

CLI Reference

landpyre refresh

landpyre search QUERY

landpyre list

landpyre manifest

landpyre download

landpyre verify

landpyre config

landpyre doctor

SDK Reference

LandpyreClient

Key Models

Filtering Logic

Output Structure

Links

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`landpyre refresh`

`landpyre search QUERY`

`landpyre list`

`landpyre manifest`

`landpyre download`

`landpyre verify`

`landpyre config`

`landpyre doctor`

`LandpyreClient`