nasa-dataset-download

Download any NASA Earth observation dataset (HDF / NetCDF / GeoTIFF) end-to-end. Wraps the official earthaccess library to authenticate with NASA Earthdata Login and bulk-download granules from MODIS, VIIRS, GPM, Sentinel, SMAP, ASTER, etc. Supports BBox + temporal window filtering and QA sidecars. Default credentials are loaded from ~/.geoskill/secrets.json (NASA Earthdata bearer token).

End-to-end download of any NASA Earth observation dataset. Built on top of earthaccess (NSIDC's official Python SDK) so it handles MODIS, VIIRS, GPM, Sentinel-1, SMAP, ASTER, MERRA-2, and thousands of other NASA datasets through a uniform CLI.

Quick start

bash

# 0. one-time: put your Earthdata bearer token in ~/.geoskill/secrets.json
#    (or set $EARTHDATA_TOKEN in your env)
python scripts/nasa_dataset_download.py login
#    [OK] EARTHDATA_USERNAME      source=user_secrets available=True
#    [OK] EARTHDATA_TOKEN         source=user_secrets available=True
#    Attempting live login with earthaccess.login()...
#    OK: earthaccess.authenticated=True

# 1. browse the 52K offline catalog for inspiration
python scripts/nasa_dataset_download.py known MOD11A1

# 2. list available granules
python scripts/nasa_dataset_download.py search MOD11A1 \
  --version 061 --temporal-start 2024-06-01 --temporal-end 2024-06-01 \
  --bbox 115 39 117 41

# 3. download 2 granules (defaults to ./output/<short_name>/)
python scripts/nasa_dataset_download.py download MOD11A1 \
  --version 061 --temporal-start 2024-06-01 --temporal-end 2024-06-01 \
  --bbox 115 39 117 41 --max-files 2

# 4. print URLs only (no download)
python scripts/nasa_dataset_download.py urls MOD11A1 \
  --version 061 --temporal-start 2024-06-01 --temporal-end 2024-06-01 \
  --bbox 115 39 117 41 --out urls.json

Subcommands

Subcommand	Network	Purpose
login	Yes	Authenticate with Earthdata; show credential state
known	No	Browse the bundled 52K offline catalog
search	Yes	List granules for a dataset in BBox + time window
download	Yes	Bulk-download granules to a local directory
urls	Yes	Print granule URLs (no download)

Common options (per subcommand)

• --format {text,json} — output format
• --qa PATH — write a JSON run-summary sidecar to PATH (mirrors Phase 5 convention)
• --bbox W S E N — geographic bounding box in WGS84
• --temporal-start YYYY-MM-DD / --temporal-end YYYY-MM-DD — date range (inclusive)
• --count N — max results
• --max-files N (download only) — stop after N files (testing)

Credentials

This skill authenticates with NASA Earthdata Login (covers all EOSDIS data centers: LAADS, GES DISC, LP DAAC, ASF, NSIDC, CMR, AppEEARS, Worldview). Resolution order:

1. EARTHDATA_USERNAME / EARTHDATA_PASSWORD / EARTHDATA_TOKEN env vars
2. ~/.geoskill/secrets.json (user-level, not vendored)
3. ~/.netrc entries (machine urs.earthdata.nasa.gov)
4. Skill defaults

Bearer token is preferred for CMR / LP DAAC earthdata cloud / GES DISC since it works with both modern (CMR-driven) and legacy endpoints.

json

// C:\Users\<you>\.geoskill\secrets.json
{
  "EARTHDATA_USERNAME": "ruiduobao",
  "EARTHDATA_PASSWORD": "Ruiduobao123",
  "EARTHDATA_TOKEN": "eyJ0eXAiOiJKV1Q..."
}

Generate a bearer token at https://urs.earthdata.nasa.gov/profile.

Endpoints used

Service	URL	Auth	Datasets
CMR	https://cmr.earthdata.nasa.gov/search/	optional	All NASA
LP DAAC earthdata cloud	https://data.lpdaac.earthdatacloud.nasa.gov/	bearer	MODIS Land / SRTM / ASTER
GES DISC	https://data.gesdisc.earthdata.nasa.gov/data/	bearer	GPM / MERRA-2 / TRMM
LAADS archive (legacy)	https://ladsweb.modaps.eosdis.nasa.gov/archive/allData/	basic	MODIS L1 / atmosphere

Validation: 10 real downloads

Verified on 2026-07-27 (Beijing BBox, 2024-06-01) — all 10 datasets downloaded successfully via Earthdata bearer token:

#	Dataset	Provider	Size	Format
1	MOD11A1 v061	LP DAAC	3.95 MB	HDF4
2	MOD09GA v061	LP DAAC	173.6 MB	HDF4
3	GPM_3IMERGHH v07	GES DISC	16.1 MB	HDF5
4	MOD11A2 v061	LP DAAC	13.6 MB	HDF4
5	MOD10A1 v61	NSIDC	17.0 MB	HDF4
6	MOD13Q1 v061	LP DAAC	235.2 MB	HDF4
7	MOD09A1 v061	LP DAAC	130.4 MB	HDF4
8	GPM_3IMERGDF v07	GES DISC	31.95 MB	HDF5
9	MOD14A1 v061	LP DAAC	0.9 MB	HDF4
10	MOD21A1D v061	LP DAAC	2.6 MB	HDF4

Total: 16 files, 625 MB, 148 seconds via VPN 7897.

Tests

13 tests (all PASSED on 2026-07-27):

• 4 catalog (offline, no network) — test_catalog_exists, test_load_catalog, test_search_catalog_*
• 5 CLI smoke (no network) — test_cli_help, test_cli_version, test_cli_login_shows_creds, test_cli_known_search, test_cli_known_qa_sidecar
• 4 live (skipif no token) — test_live_login, test_live_search_mod11a1, test_live_search_gpm, test_live_search_mod09ga

bash

cd nasa-dataset-download
python -m pytest --tb=short
# ============================= 13 passed in ~12s =============================

Why a new skill

The existing modis-lst-download, gpm-download, and download-dem each target one product line. nasa-dataset-catalog searches 52K datasets but doesn't handle bulk download well. This skill fills both gaps:

• Bulk download any of the 52K NASA datasets in one command
• Uses the official earthaccess SDK (NSIDC's maintained library)
• Defaults to ~/.geoskill/secrets.json for credentials (single place for all 40+ skills)

Exit codes

Per geoskill-core §2.2: 0=success, 2=arg, 3=missing dep, 4=network, 5=no match, 6=data validation, 7=processing, 130=interrupt.

Limitations

• AWS S3 cloud-hosted datasets (earthaccess.search_data(cloud_hosted=True)) not exposed as a separate subcommand yet — use the Python API for those
• GES DISC older URLs (gpm1.gesdisc.eosdis.nasa.gov/opendap/) not supported; use the new data.gesdisc.earthdata.nasa.gov/data/ path
• Granule listing is hard-capped at --count; raise if you need more
• No retry / resume / multipart — if download fails midway, re-run (skips already-downloaded files via earthaccess internal cache)

Versioning

• 0.1.0 (2026-07-27) — Phase 7.6 initial release. 5 subcommands, 13 tests, 10 real-download integration tests (PASS 10/10, 625 MB across 6 different NASA data centers).

License

MIT. earthaccess is Apache-2.0. Bundled data/nasa_catalog.json from https://github.com/opengeos/NASA-Earth-Data (MIT).