pygeofetch Documentation

# Username / password (USGS, NASA, Copernicus)
pygeofetch auth add usgs --username YOUR_USER --password YOUR_PASS
pygeofetch auth add copernicus --username email@example.com --password PASS
pygeofetch auth add nasa_earthdata --username USER --password PASS

# API key (Planet, OpenTopography, TerraBotics, Airbus)
pygeofetch auth add planet --api-key YOUR_API_KEY
pygeofetch auth add opentopography --api-key YOUR_KEY

# OAuth2 client credentials (Sentinel Hub)
pygeofetch auth add sentinel_hub --client-id YOUR_ID --client-secret YOUR_SECRET

# Interactive login — prompts for all fields
pygeofetch auth login copernicus

# List, test, remove
pygeofetch auth list
pygeofetch auth test usgs
pygeofetch auth remove planet --yes

# Export backup (WARNING: contains secrets — store securely)
pygeofetch auth export --output creds_backup.json

# Format: pygeofetch_{PROVIDER}_{FIELD}
export pygeofetch_USGS_USERNAME=myuser
export pygeofetch_USGS_PASSWORD=mypass
export pygeofetch_PLANET_API_KEY=PL-abc123
export pygeofetch_COPERNICUS_USERNAME=email@example.com
export pygeofetch_COPERNICUS_PASSWORD=pass
export pygeofetch_NASA_EARTHDATA_USERNAME=user
export pygeofetch_OPENTOPOGRAPHY_API_KEY=mykey
export pygeofetch_SENTINEL_HUB_CLIENT_ID=id
export pygeofetch_SENTINEL_HUB_CLIENT_SECRET=secret

# Global settings
export pygeofetch_LOG_LEVEL=DEBUG
export pygeofetch_DOWNLOAD__PARALLEL=8
export pygeofetch_CACHE__TTL_SECONDS=7200

# Basic — download 3 scenes from search results
pygeofetch download run \
  --from-search results.geojson \
  --output ./data/ \
  --parallel 2 \
  --max-items 3

# RGB bands only — ~150 MB vs 600 MB for full Sentinel-2 scene
pygeofetch download run \
  --from-search results.geojson \
  --output ./data/ \
  --bands "B02,B03,B04" \
  --max-items 5

# Full options — checksum, resume, bandwidth throttle, Slack notify
pygeofetch download run \
  --from-search results.geojson \
  --output ./data/ \
  --parallel 4 \
  --retry 5 \
  --verify-checksum \
  --resume \
  --bandwidth-limit 10MB \
  --priority high \
  --on-failure skip \
  --notify webhook:https://hooks.slack.com/services/YOUR/WEBHOOK

# Post-processing chain
pygeofetch download run \
  --from-search results.geojson \
  --output ./processed/ \
  --post-process "unzip,reproject:EPSG:4326,compress:lzw,cog"

# NDVI workflow — download Red + NIR, compute NDVI, export COG
pygeofetch download run \
  --from-search results.geojson \
  --bands "B04,B08" \
  --post-process "reproject:EPSG:4326,ndvi,cog" \
  --output ./ndvi/

from pathlib import Path
from pygeofetch import pygeofetch
from pygeofetch.models import SearchQuery, DownloadOptions

# Initialize client
client = pygeofetch()

# Add credentials (or use env vars)
client.add_credentials("usgs", username="user", password="pass")
client.add_credentials("planet", api_key="PL_KEY")

# Search across multiple providers
results = client.search(
    SearchQuery(
        bbox=(-74.1, 40.6, -73.7, 40.9),
        start_date="2024-01-01",
        end_date="2024-06-01",
        cloud_cover_max=20,
        max_results=50,
        sort_by="cloud_cover",
    ),
    providers=["usgs", "copernicus", "planetary_computer", "aws_earth"],
)

print(f"Found {len(results)} scenes")
for r in results[:3]:
    print(f"  {r.id} | {r.datetime} | {r.cloud_cover:.1f}% cloud")

# Download top 5 results
download_results = client.download(
    results[:5],
    destination=Path("./data/"),
    options=DownloadOptions(
        parallel=4,
        verify_checksum=True,
        resume=True,
        bands=["B02", "B03", "B04"],
        post_process=["reproject:EPSG:4326", "cog"],
    ),
)

for dr in download_results:
    if dr.success:
        print(f"  ✓ {dr.data_id} ({dr.bytes_downloaded // 1024 // 1024:.1f} MB)")
    else:
        print(f"  ✗ {dr.data_id}: {dr.error}")

download:
  parallel: 4
  retry_attempts: 5
  retry_delay_seconds: 1.0
  retry_max_delay_seconds: 60.0
  retry_jitter: true
  verify_checksum: false
  checksum_algorithm: sha256     # md5, sha256, sha512
  chunk_size_mb: 10
  resume: true
  bandwidth_limit_mbps: null     # null = unlimited
  overwrite_existing: false
  notify_on_completion: null     # webhook:URL or email:ADDRESS
  notify_on_failure: null
  on_failure: skip               # skip, abort, retry

cache:
  enabled: true
  ttl_seconds: 3600
  max_size_gb: 10
  location: ~/.pygeofetch/cache

search:
  default_providers: []
  max_results: 100
  timeout_seconds: 60
  on_provider_failure: skip
  sort_by: datetime
  sort_order: desc

auth:
  storage_backend: keyring       # keyring or file
  keyring_service: pygeofetch
  file_path: ~/.pygeofetch/credentials.enc

proxy:
  http_proxy: null
  https_proxy: null
  no_proxy: []

logging:
  level: INFO
  format: console                # console, json
  file: null
  max_file_size_mb: 10
  backup_count: 3

providers:
  planetary_computer:
    endpoint: https://planetarycomputer.microsoft.com/api/stac/v1
    timeout: 60
  element84:
    endpoint: https://earth-search.aws.element84.com/v1
    timeout: 60
  copernicus:
    endpoint: https://catalogue.dataspace.copernicus.eu/resto/api/
    timeout: 45
  planet:
    endpoint: https://api.planet.com/data/v1/
    rate_limit: 100
  usgs:
    endpoint: https://m2m.cr.usgs.gov/api/api/json/stable/
    timeout: 60

# Show the merged effective configuration
pygeofetch config show

# Get a specific key
pygeofetch config get download.parallel

# Set a value
pygeofetch config set download.parallel 8
pygeofetch config set cache.ttl_seconds 7200
pygeofetch config set search.default_providers "aws_earth,planetary_computer"

# Show config file path
pygeofetch config path

# Reset to defaults
pygeofetch config reset

# Skip failing providers — return partial results from others
pygeofetch search run --providers copernicus,usgs,planet \
  --on-provider-failure skip

# Abort entirely if any provider fails
pygeofetch search run --providers copernicus,usgs \
  --on-provider-failure abort

# Auto-retry failing providers (up to 3 attempts)
pygeofetch search run --providers copernicus \
  --on-provider-failure retry

# Install dev dependencies
pip install -e ".[dev,all]"

# Run all tests
pytest tests/ -v

# With coverage report
pytest tests/ -v --cov=pygeofetch --cov-report=html
open htmlcov/index.html

# Unit tests only (fast, no network)
pytest tests/unit/ -v

# Integration tests (requires real credentials)
pytest tests/integration/ -v --run-integration

# Run a specific test file
pytest tests/unit/test_search.py -v

# With hypothesis property-based testing
pytest tests/property/ -v --hypothesis-seed=12345

tests/
├── unit/
│   ├── test_search.py         # SearchQuery, provider adapters
│   ├── test_download.py       # DownloadOptions, resume, checksum
│   ├── test_auth.py           # Keyring, env vars, credential storage
│   ├── test_pipeline.py       # YAML parsing, step execution
│   ├── test_postprocess.py    # Processing chain actions
│   └── test_config.py         # Layered config merging
├── integration/
│   ├── test_aws_earth.py      # Live AWS Earth Open Data
│   ├── test_planetary.py      # Live Planetary Computer
│   └── conftest.py
├── property/
│   └── test_models.py         # hypothesis tests
├── cli/
│   └── test_cli_workflow.py   # CliRunner end-to-end
└── cassettes/                 # VCR HTTP recordings