nasa-dataset-download

end-to-end download of any NASA Earth observation dataset. wraps the official earthaccess SDK from NSIDC to handle MODIS, VIIRS, GPM, Sentinel-1, SMAP, ASTER, MERRA-2, and thousands of NASA datasets through a single CLI. use this when you need to bulk-download granules across geographic areas and time windows from any EOSDIS data center (LP DAAC, GES DISC, LAADS, NSIDC, ASF, CMR).

intent

this skill downloads NASA Earth observation data at scale. you provide a dataset short_name (or human-readable description), a bounding box, a date range, and a file count limit. the skill queries the CMR (Common Metadata Repository), filters granules by your constraints, and downloads them locally with optional dry-run and QA metadata. it handles authentication via Earthdata Login, resolves alias descriptions to canonical dataset names, and exits with proper error codes when no granules match or network issues occur.

inputs

required parameters:

• DATASET: dataset short_name (e.g. MOD11A1, GPM_3IMERGHH) or human description (e.g. "land surface temperature"). descriptions trigger alias-map lookup; if no alias match, multi-word AND search across the offline catalog is attempted.

optional parameters (all subcommands):

• --format {text,json} , output format; default=text
• --qa PATH , write JSON run-summary sidecar to PATH (mirrors Phase 5 convention)
• --bbox W S E N , bounding box in WGS84 decimal degrees (west, south, east, north); default=global
• --temporal-start YYYY-MM-DD , inclusive start date; no default (searches all available)
• --temporal-end YYYY-MM-DD , inclusive end date; defaults to today if start is set
• --count N , max results per query; default=10
• --version VERSION , dataset version (e.g. 061 for MOD11A1); optional
• --no-alias-resolve , skip alias-map hint when dataset name looks like a description

optional parameters (download subcommand only):

• --max-files N , actually limit downloads to N granules; default=1
• --dry-run , print what would be downloaded without writing files

external connections:

• NASA Earthdata Login: CMR, LP DAAC earthdata cloud, GES DISC, LAADS archive, NSIDC. requires bearer token or username/password pair.
• CMR (Common Metadata Repository): https://cmr.earthdata.nasa.gov/search/ , dataset catalog (optional auth, all NASA data)
• LP DAAC: https://data.lpdaac.earthdatacloud.nasa.gov/ , MODIS Land, SRTM, ASTER (requires bearer token)
• GES DISC: https://data.gesdisc.earthdata.nasa.gov/data/ , GPM, MERRA-2, TRMM (requires bearer token)
• LAADS: https://ladsweb.modaps.eosdis.nasa.gov/archive/allData/ , MODIS L1, atmosphere (basic auth or token)

credentials (resolution order):

1. env vars: EARTHDATA_USERNAME, EARTHDATA_PASSWORD, EARTHDATA_TOKEN
2. ~/.geoskill/secrets.json (JSON file with keys EARTHDATA_USERNAME, EARTHDATA_PASSWORD, EARTHDATA_TOKEN)
3. ~/.netrc entries (machine urs.earthdata.nasa.gov)
4. interactive prompt (if all above fail and login subcommand is run)

setup guidance:

• generate a bearer token at https://urs.earthdata.nasa.gov/profile (recommended for cloud-hosted datasets)
• store in ~/.geoskill/secrets.json:

  {
    "EARTHDATA_USERNAME": "your_username",
    "EARTHDATA_PASSWORD": "your_password",
    "EARTHDATA_TOKEN": "eyJ0eXAiOiJKV1Q..."
  }
  

• or set env var: export EARTHDATA_TOKEN=eyJ0eXAiOiJKV1Q...

bundled data:

• data/nasa_catalog.json , 52K+ offline dataset records (MIT license from opengeos/NASA-Earth-Data)
• data/aliases.json , 50-entry alias map (description to short_name); entries: MODIS LST, surface reflectance, land cover, vegetation index, NDVI, snow cover, sea ice, precipitation, IMERG, GPM, rainfall, soil moisture, SMAP, SST, ocean color, active fire, evapotranspiration, Sentinel-1, Landsat, DEM, ASTER, LAI, GPP, ET, and others

procedure

step 1: login and verify credentials

input: none (reads from env, ~/.geoskill/secrets.json, or ~/.netrc) action: run python scripts/nasa_dataset_download.py login output: console output showing credential source and earthaccess auth state (authenticated=True or False); if auth fails, error message with next steps edge case: if token is expired, earthaccess.login() fails; regenerate token at https://urs.earthdata.nasa.gov/profile and retry

step 2: (optional) browse known datasets

input: optional QUERY string (e.g. "land surface temperature" or MOD11A1) action: run python scripts/nasa_dataset_download.py known [QUERY] (or known with no args to list all 52K) output: text or JSON list of matching catalog records (short_name, description, temporal_range) edge case: multi-word queries use AND logic (all words must match in title/description); may surface false positives; alias matches are printed as hints

step 3: search for granules

input: DATASET, optional --bbox, --temporal-start, --temporal-end, --version, --count, --format action: run python scripts/nasa_dataset_download.py search <DATASET> [OPTIONS] output: list of matching granules with granule_id, size_in_mb, acquisition date, and data_links; JSON sidecar if --qa PATH is set edge case: if DATASET is a description, alias lookup is attempted and a hint is printed to stderr suggesting canonical short_names; if 0 granules match, exit code 5 is returned with diagnostic message

step 4a (download): preview with dry-run

input: DATASET, --bbox, --temporal-start, --temporal-end, --version, --max-files, --dry-run action: run python scripts/nasa_dataset_download.py download <DATASET> --dry-run [OPTIONS] output: console list of granule URLs and sizes that would be downloaded (no files written); JSON sidecar if --qa PATH is set edge case: none (safe to run multiple times)

step 4b (download): actual download

input: DATASET, --bbox, --temporal-start, --temporal-end, --version, --max-files, --format action: run python scripts/nasa_dataset_download.py download <DATASET> [OPTIONS] (omit --dry-run) output: files written to ./output/<short_name>/ (default) or custom path; JSON sidecar if --qa PATH is set; console log of downloaded file paths and total size edge case: if a file already exists locally (per earthaccess internal cache), it is skipped; if network timeout occurs mid-download, re-run command to resume; if --max-files is set, download stops after N granules

step 5 (optional): extract URLs only

input: DATASET, --bbox, --temporal-start, --temporal-end, --version, --count, --out PATH action: run python scripts/nasa_dataset_download.py urls <DATASET> [OPTIONS] --out urls.json output: JSON array of granule URLs written to PATH; structured metadata (granule_id, size, cloud_hosted flag, data_links) included edge case: none (no files downloaded, pure metadata extraction)

decision points

if DATASET name is a human-readable description (not a canonical short_name):

• check if it matches an entry in data/aliases.json (50 hardcoded entries like "land surface temperature" -> ["MOD11A1", "MOD11A2", "MOD11B", ...])
• if alias match found, print hint to stderr suggesting canonical short_names and exit (allow user to re-run with canonical name)
• if no alias match, fall back to multi-word AND search across the offline catalog (all 52K records); surface any records whose title/description match all query words
• allow --no-alias-resolve flag to skip alias-map step entirely

if 0 granules match the search criteria:

• return exit code 5 (per geoskill-core §2.2)
• print error message to stderr listing possible causes: dataset name may be a description, date range may be out of range, spelling errors, etc.
• print suggestions: try known "<DATASET>" to find similar short_names; check spelling against canonical names (e.g. MOD11A1 not MOD11A-1)

if network timeout or connection error occurs:

• return exit code 4 (per geoskill-core §2.2)
• print error message to stderr with service name (CMR, LP DAAC, GES DISC, LAADS) and retry instructions

if Earthdata credentials are missing or expired:

• return exit code 3 (missing dependency / auth) if interactive prompt cannot be completed
• print error message to stderr with setup instructions: generate token at https://urs.earthdata.nasa.gov/profile and store in ~/.geoskill/secrets.json or env var
• if token is set but rejected by CMR, suggest regenerating token

if --max-files N is set (download only):

• stop download loop after N granules; do not fetch more than N granules from CMR query result
• print total count of files downloaded and total size

if --dry-run is set (download only):

• omit actual file writes; print what would be downloaded to console; allow --qa sidecar to be written (metadata-only)

if --bbox or temporal range filters are omitted:

• search defaults to global spatial extent and all available time periods for the dataset (or today if only start date is provided)

if --format json is set:

• output granule list as JSON array with keys: granule_id, short_name, size_in_mb, temporal_range_start, temporal_range_end, acquisition_date, cloud_hosted, data_links, umm_metadata (partial)

output contract

success case (search / urls subcommands):

• stdout: granule list (text: newline-delimited human-readable rows; json: structured array)
• stderr: diagnostic hints (if description-style dataset name is used)
• sidecar (if --qa PATH): JSON object with keys:
  • subcommand: "search" or "urls"
  • dataset: canonical short_name
  • query_bbox: [W, S, E, N] or null
  • query_temporal_start: ISO 8601 date or null
  • query_temporal_end: ISO 8601 date or null
  • result_count: integer (granules found)
  • total_size_mb: float (sum of all granule sizes)
  • execution_time_seconds: float
  • exit_code: 0

success case (download subcommand):

• files written to ./output/<short_name>/ (default) or custom path specified in command
• stdout: download progress log (granule_id, file path, size)
• stderr: none (or informational messages)
• sidecar (if --qa PATH): JSON object with keys:
  • subcommand: "download"
  • dataset: canonical short_name
  • query_bbox: [W, S, E, N] or null
  • query_temporal_start: ISO 8601 date or null
  • query_temporal_end: ISO 8601 date or null
  • files_downloaded: integer
  • files_skipped: integer (already cached locally)
  • total_size_mb: float
  • local_output_dir: absolute path
  • execution_time_seconds: float
  • exit_code: 0

failure case (exit code 4 - network):

• stderr: error message with service name and timeout details
• sidecar (if --qa PATH): JSON object with exit_code: 4 and error_message key

failure case (exit code 5 - no match):

• stderr: "no granules found. Possible causes: ..." message with troubleshooting hints
• sidecar (if --qa PATH): JSON object with exit_code: 5, result_count: 0, and suggestions key

failure case (exit code 3 - auth):

• stderr: "Earthdata authentication failed" with setup instructions
• sidecar (if --qa PATH): JSON object with exit_code: 3 and error_message key

failure case (exit code 2 - arg):

• stderr: usage message and specific argument error
• sidecar (if --qa PATH): JSON object with exit_code: 2 and error_message key

outcome signal

the skill worked if any of the following is true:

1. login subcommand: console output shows [OK] EARTHDATA_TOKEN source=user_secrets available=True and earthaccess.authenticated=True

2. known subcommand: console lists 52K+ dataset records or a filtered subset with short_name, description, and temporal range; if a description is provided, alias-matched records are marked

3. search subcommand: console lists 1+ granules with granule_id, size_in_mb, acquisition_date, and download URLs; exit code is 0; if --qa was set, sidecar JSON exists and contains result_count > 0

4. download subcommand: files appear in ./output/<short_name>/ with expected names and sizes; console log shows "downloaded: "; exit code is 0; if --qa was set, sidecar JSON shows files_downloaded > 0 and total_size_mb > 0

5. urls subcommand: JSON file written to --out path contains structured array with granule_id, size_in_mb, and data_links keys; exit code is 0

6. dry-run (download): console lists granule URLs and sizes without writing any files; exit code is 0

7. error handling: when 0 granules match, exit code is 5 (not 0 or 1); stderr contains "no granules found" message with suggestions; when auth fails, exit code is 3 and stderr points to setup instructions; when network timeout occurs, exit code is 4