{"id":26223524,"url":"https://github.com/cholmes/sh-downloader","last_synced_at":"2026-04-19T21:37:17.663Z","repository":{"id":280886936,"uuid":"943502019","full_name":"cholmes/sh-downloader","owner":"cholmes","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-05T21:42:12.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-05T21:42:29.495Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cholmes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-05T20:09:23.000Z","updated_at":"2025-03-05T21:42:15.000Z","dependencies_parsed_at":"2025-03-05T21:42:34.563Z","dependency_job_id":"6d1247d4-d003-4362-9f40-ea09327fc451","html_url":"https://github.com/cholmes/sh-downloader","commit_stats":null,"previous_names":["cholmes/sh-downloader"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cholmes%2Fsh-downloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cholmes%2Fsh-downloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cholmes%2Fsh-downloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cholmes%2Fsh-downloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cholmes","download_url":"https://codeload.github.com/cholmes/sh-downloader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243264071,"owners_count":20263299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-12T17:36:05.460Z","updated_at":"2025-12-26T21:49:06.608Z","avatar_url":"https://github.com/cholmes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sentinel Hub Downloader\n\nA command-line tool to download GeoTIFF data from Sentinel Hub. It is \ncurrently focused on BYOC data, so far only tested with Planet PV's of\nSoil Water Content and Crop Biomass. But it attempts to work against\nany BYOC collection, automatically discovering the bands and metadata.\n\nIt has only been tested against smaller files, and works just with the\nprocess api. Making it work with larger areas will likely require batch API\nand some iterative approach.\n\n## Features\n\n- Search and download BYOC and Sentinel imagery based on time range and area of interest\n- Easy-to-use command line interface\n- Support for various spatial filters (bounding box, GeoJSON)\n- Configurable output directory \n- Automatically discovers bands and metadata for BYOC collections\n- Lets users supply custom evalscripts\n- Supports various output data types and nodata values\n\n## Installation\n\nClone the repository and then install the package:\n\n```bash\npip install sh-downloader\n```\n\n## Configuration\n\nBefore using the tool, you need to configure your Sentinel Hub credentials:\n\n```\nshdown config --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n```\n\nThis will create a configuration file at `~/.sentinelhub/config.json`.\n\n### Command Help\n\n```\nshdown --help\n\nUsage: shdown [OPTIONS] COMMAND [ARGS]...\n\n  Command line tool for downloading data from Sentinel Hub.\n\nOptions:\n  --debug / --no-debug  Enable debug logging\n  --help                Show this message and exit.\n\nCommands:\n  byoc        Download a time series of images from a BYOC collection.\n  config      Configure Sentinel Hub credentials.\n  info        Get information about a collection.\n  search      Search for available images.\n```\n\n## Usage\n\n### Search for available images\n\nSearch for available Sentinel-2 L2A images in a specific area and time range:\n\n```\nshdown search --collection sentinel-2-l2a --bbox 14.0 45.0 14.5 45.5 --time-from 2023-01-01 --time-to 2023-01-31\n```\n\n#### Search Command Help\n\n```\nshdown search --help\n\nUsage: shdown search [OPTIONS]\n\n  Search for available satellite imagery without downloading.\n\nOptions:\n  -c, --collection [sentinel-1-grd|sentinel-2-l1c|sentinel-2-l2a|sentinel-3-olci|sentinel-5p-l2|byoc]\n                                  Sentinel data collection to search\n                                  [required]\n  --byoc-id TEXT                  BYOC collection ID (required if collection\n                                  is 'byoc')\n  -s, --start TEXT                Start date (YYYY-MM-DD). Defaults to 30 days\n                                  ago.\n  -e, --end TEXT                  End date (YYYY-MM-DD). Defaults to today.\n  -b, --bbox TEXT                 Bounding box as\n                                  min_lon,min_lat,max_lon,max_lat. Default is\n                                  global.\n  -m, --max-cloud-cover FLOAT     Maximum cloud cover percentage (0-100). Only\n                                  applies to optical sensors.\n  -l, --limit INTEGER             Maximum number of results to display.\n                                  Default is 10.\n  --help                          Show this message and exit.\n```\n\nSample output:\n\n```\nFound 8 images:\n2023-01-30T10:20:19Z - Cloud cover: 0.00%\n2023-01-27T10:30:21Z - Cloud cover: 1.23%\n2023-01-25T10:20:19Z - Cloud cover: 0.45%\n2023-01-22T10:30:21Z - Cloud cover: 2.67%\n2023-01-20T10:20:19Z - Cloud cover: 0.12%\n2023-01-17T10:30:21Z - Cloud cover: 3.45%\n2023-01-15T10:20:19Z - Cloud cover: 1.78%\n2023-01-12T10:30:21Z - Cloud cover: 0.89%\n```\n\n### Download a specific image\n\nDownload a specific Sentinel-2 L2A image by date:\n\n```\nshdown download --collection sentinel-2-l2a --bbox 14.0 45.0 14.5 45.5 --date 2023-01-30 --output-dir ./images\n```\n\n#### Download Command Help\n\n```\nshdown download --help\n\nUsage: shdown download [OPTIONS]\n\n  Download a specific image from Sentinel Hub.\n\nOptions:\n  --collection TEXT         Collection name (e.g., sentinel-2-l2a)  [required]\n  --bbox FLOAT...           Bounding box as min_lon min_lat max_lon max_lat\n                            [required]\n  --date TEXT               Date to download (YYYY-MM-DD)\n  --image-id TEXT           Specific image ID to download\n  --output-dir TEXT         Directory to save the downloaded image\n  --filename TEXT           Filename for the downloaded image\n  --byoc-id TEXT            BYOC collection ID (required if collection is\n                            'byoc')\n  --size INTEGER...         Size of the output image as width height\n  --bands TEXT              Comma-separated list of bands to include\n  --data-type TEXT          Output data type (AUTO, UINT8, UINT16, FLOAT32)\n  --nodata FLOAT            Value to use for nodata pixels\n  --scale FLOAT             Scale factor for the output image\n  --help                    Show this message and exit.\n```\n\nSample output:\n\nDownloading image for 2023-01-30...\nImage saved to ./images/sentinel-2-l2a_2023-01-30.tiff\n\n### Download BYOC (Bring Your Own Collection) data\n\nDownload data from a custom collection:\n\n```\nshdown byoc --byoc-id YOUR_BYOC_COLLECTION_ID --time-from 2024-05-01 \n```\n\n#### BYOC Command Help\n\n```\n % shdown byoc --help\nUsage: shdown byoc [OPTIONS]\n\n  Download images from a BYOC collection.\n\nOptions:\n  --byoc-id TEXT                  BYOC collection ID  [required]\n  -i, --image-id TEXT             Image ID to download\n  -s, --start TEXT                Start date (YYYY-MM-DD). Defaults to 30 days\n                                  ago.\n  -e, --end TEXT                  End date (YYYY-MM-DD). Defaults to today.\n  -b, --bbox TEXT                 Bounding box in format 'minx,miny,maxx,maxy'\n                                  (WGS84). Optional - if not provided, will\n                                  use each image's own bbox.\n  -o, --output-dir TEXT           Output directory for downloaded images\n  --size TEXT                     Size of the output image as width,height\n                                  (default: 512,512)\n  -t, --time-difference INTEGER   Minimum days between downloaded images\n                                  (default: None - download all images)\n  --all-dates / --filter-dates    Download all available dates without\n                                  filtering (overrides --time-difference)\n  -f, --filename-template TEXT    Template for filenames (default:\n                                  'BYOC_{byoc_id}_{date}.tiff')\n  --evalscript-file TEXT          Path to a file containing a custom\n                                  evalscript\n  --bands TEXT                    Comma-separated list of band names to\n                                  download (e.g., 'SWC,dataMask')\n  --auto-discover-bands / --no-auto-discover-bands\n                                   Automatically discover and include all bands\n                                  (default: True)\n  --nodata FLOAT                  Value to use for nodata pixels in the output\n                                  GeoTIFF\n  --scale FLOAT                   Value to set as SCALE metadata in the output\n                                  GeoTIFF\n  --data-type [auto|int8|int16|int32|int64|uint8|uint16|uint32|uint64|float16|float32|float64|cint16|cint32|cfloat32|cfloat64]\n                                  Output data type (default: AUTO)\n  --help                          Show this message and exit.                           \n```\n\n\nGet metadata about a collection:\n\n```\nshdown info --collection --collection byoc --byo\n```\n\n#### Info Command Help\n\n```\nshdown info --help\n\nUsage: shdown info [OPTIONS]\n\n  Get information about a collection.\n\nOptions:\n  --collection TEXT  Collection name (e.g., sentinel-2-l2a)  [required]\n  --byoc-id TEXT     BYOC collection ID (required if collection is 'byoc')\n  --help             Show this message and exit.\n```\n\nSample output:\n\nCollection: sentinel-2-l2a\nDescription: Sentinel-2 L2A imagery\nAvailable bands:\n  - B01: Coastal aerosol (443 nm)\n  - B02: Blue (490 nm)\n  - B03: Green (560 nm)\n  - B04: Red (665 nm)\n  - B05: Vegetation Red Edge (705 nm)\n  - B06: Vegetation Red Edge (740 nm)\n  - B07: Vegetation Red Edge (783 nm)\n  - B08: NIR (842 nm)\n  - B8A: Vegetation Red Edge (865 nm)\n  - B09: Water vapour (945 nm)\n  - B11: SWIR (1610 nm)\n  - B12: SWIR (2190 nm)\n  - SCL: Scene classification\n\n## Advanced Usage\n\n### Specify bands to download\n\nDownload only specific bands from a collection:\n\n```\nshdown download --collection sentinel-2-l2a --bbox 14.0 45.0 14.5 45.5 --date 2023-01-30 --bands B04,B03,B02 --output-dir ./images\n```\n\nSample output:\n\nDownloading image for 2023-01-30...\nUsing specified bands: ['B04', 'B03', 'B02']\nImage saved to ./images/sentinel-2-l2a_2023-01-30.tiff\n\n### Set output data type\n\nSpecify the output data type for downloaded images:\n    \n```\nshdown download --collection sentinel-2-l2a --bbox 14.0 45.0 14.5 45.5 --date 2023-01-30 --data-type uint16 --output-dir ./images\n```\n\nSample output:\n\nDownloading image for 2023-01-30...\nUsing data type: UINT16\nImage saved to ./images/sentinel-2-l2a_2023-01-30.tiff\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n\n## TODO's\n\n- Start issue tracker to put these in\n- clean up extra gdal files\n- option to provide a template for file naming\n- show progress as images are downloading / completing\n- make it so 'search' works nicer with byoc (same command, detect uuid and use it as id)\n- Try out cloud filtering for PS data, and if it works then check stac metadata for cloud cover dynamically\n- Checking of non-byoc collections, and raise error on bad collection names before getting 400 from api not recognizing (like hit collections end point. Perhaps get the list of collections on init? At least the non-byoc ones)\n- collection list (and filtering?) to get what collections to ask about.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcholmes%2Fsh-downloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcholmes%2Fsh-downloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcholmes%2Fsh-downloader/lists"}