{"id":29506081,"url":"https://github.com/wehrad/earthspy","last_synced_at":"2025-07-27T08:03:56.529Z","repository":{"id":37034458,"uuid":"460777031","full_name":"wehrad/earthspy","owner":"wehrad","description":"Monitor and study any place on Earth and in Near Real-Time using the Sentinel Hub services developed by the EO research team at Sinergise","archived":false,"fork":false,"pushed_at":"2025-02-12T14:29:04.000Z","size":4289,"stargazers_count":63,"open_issues_count":7,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-16T22:18:03.752Z","etag":null,"topics":["earth-observation","python","satellite","sentinel-hub"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wehrad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2022-02-18T08:51:53.000Z","updated_at":"2025-05-16T07:47:36.000Z","dependencies_parsed_at":"2024-01-07T18:08:41.238Z","dependency_job_id":"fb2cd1c9-9441-4915-a35d-319025753ae6","html_url":"https://github.com/wehrad/earthspy","commit_stats":{"total_commits":235,"total_committers":2,"mean_commits":117.5,"dds":0.004255319148936176,"last_synced_commit":"9ee52fba8ed41af57331c25cd252142f4a12de80"},"previous_names":["wehrad/earthspy"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/wehrad/earthspy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wehrad%2Fearthspy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wehrad%2Fearthspy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wehrad%2Fearthspy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wehrad%2Fearthspy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wehrad","download_url":"https://codeload.github.com/wehrad/earthspy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wehrad%2Fearthspy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267327534,"owners_count":24069442,"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","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["earth-observation","python","satellite","sentinel-hub"],"created_at":"2025-07-16T01:20:29.606Z","updated_at":"2025-07-27T08:03:56.524Z","avatar_url":"https://github.com/wehrad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Continuous integration](https://github.com/AdrienWehrle/earthspy/workflows/CI/badge.svg)](https://github.com/AdrienWehrle/earthspy/actions)\n[![CodeQL](https://github.com/AdrienWehrle/earthspy/actions/workflows/codeql.yml/badge.svg)](https://github.com/AdrienWehrle/earthspy/actions/workflows/codeql.yml)\n[![readthedocs](https://readthedocs.org/projects/earthspy/badge/?version=latest)]()\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com/)\n[![codecov](https://codecov.io/gh/AdrienWehrle/earthspy/branch/main/graph/badge.svg)](https://codecov.io/gh/AdrienWehrle/earthspy)\n[![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336)](https://pycqa.github.io/isort/)\n\n\n# earthspy 🛰️ :earth_africa: :earth_americas: :earth_asia:\n\n`earthspy` is a wrapper around methods for the download of satellite data offered in the [sentinelhub-py Python package](https://github.com/sentinel-hub/sentinelhub-py). This tool makes the monitoring and study of any place on Earth simple, ready to use and easily deployable for operational purposes and automated Near-Real Time (NRT) applications.\n\nAs `earthspy` is built on top of the [Sentinel Hub services](https://www.sentinel-hub.com/), it includes e.g. the data pre-processing through [custom scripts](https://docs.sentinel-hub.com/api/latest/evalscript/) allowing the user to process and download only the products needed (such as high-level indices) therefore optimizing download time and local storage.\n\n#  Table of Contents\n- [earthspy](#earthspy-%EF%B8%8F-earth_africa-earth_americas-earth_asia)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Operational Near Real-Time (NRT) deployment](#operational-near-real-time-nrt-deployment)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\n# Installation\n\nIt is recommended to install `earthspy` via [Github](https://github.com/), with [conda](https://docs.conda.io/en/latest/) and [pip](https://pip.pypa.io/en/stable/):\n\n```bash\n\n# clone repository\ngit clone git@github.com:AdrienWehrle/earthspy.git\n\n# move into earthspy directory\ncd earthspy\n\n# create conda environment\nconda env create -f environment.yml\n\n# activate conda environment\nconda activate earthspy\n\n# install earthspy\npip install -e .\n```\n\n- Using `pip` together with `conda` is usually a bad idea, but here `conda` installs all the dependencies and `pip` only sets up the associated paths, that's all! :+1:\n- Installation can be sped up using the fast cross-platform package manager [mamba](https://mamba.readthedocs.io/en/latest/) (reimplementation of the conda package manager in C++), simply use `mamba` instead of `conda` in the instructions above!\n\n\n# Usage\nAt present `earthspy` can be run within a couple of lines of Python code that execute three main tasks:\n- set up a Sentinel Hub connection (for a given Sentinel Hub account)\n- set query parameters including Sentinel Hub API variables and `earthspy` additional ones (mainly for download efficiency)\n- send request\n\nBelow is presented a simple application of `earthspy` for the download of Sentinel-2 data download around Ilulissat, Greenland for a few days in August 2019 using a True Color custom script available on Sentinel Hub's [custom script online repository](https://custom-scripts.sentinel-hub.com). All other available data collections can be found [here](https://sentinelhub-py.readthedocs.io/en/latest/examples/data_collections.html).\n\n```python\nimport earthspy.earthspy as es\n\n# auth.txt should contain username and password (first and second row)\njob = es.EarthSpy(\"/path/to/auth.txt\")\n\n# as simple as it gets\njob.set_query_parameters(\n    bounding_box=[\n        -51.13,\n        69.204,\n        -51.06,\n        69.225,\n    ],  # format from doc: [min_x, min_y, max_x, max_y]\n    time_interval=[\"2019-08-03\", \"2019-08-10\"],\n    evaluation_script=\"https://custom-scripts.sentinel-hub.com/custom-scripts/sentinel-2/true_color/script.js\",\n    data_collection=\"SENTINEL2_L2A\",\n)\n\n# and off it goes!\njob.send_sentinelhub_requests()\n```\n\nHomemade custom evalscripts can also be passed without effort to e.g. compute high-level indices (NDVI, NDSI...).\nBelow is presented an example with the default evaluation script used above (to keep it short):\n\n```python\nimport earthspy.earthspy as es\n\n# Sentinel-2 default True Color script\nexample_evalscript = \"\"\"\n    //VERSION=3\n    function setup(){\n      return{\n        input: [\"B02\", \"B03\", \"B04\", \"dataMask\"],\n        output: {bands: 4}\n      }\n    }\n\n    function evaluatePixel(sample){\n      // Set gain for visualisation\n      let gain = 2.5;\n      // Return RGB\n      return [sample.B04 * gain, sample.B03 * gain, sample.B02 * gain, sample.dataMask];\n    }\n\n    \"\"\"\n\n# auth.txt should contain username and password (first and second row)\njob = es.EarthSpy(\"/path/to/auth.txt\")\n\n# pass string to evaluation_script\njob.set_query_parameters(\n    bounding_box=[-51.13, 69.204, -51.06, 69.225],\n    time_interval=[\"2019-08-03\", \"2019-08-10\"],\n    evaluation_script=example_evalscript,\n    data_collection=\"SENTINEL2_L2A\",\n)\n\n# and off it goes!\njob.send_sentinelhub_requests()\n```\n\n[GEOJSON](https://geojson.org/) files containing a polygon corresponding to a given region of interest\nand its associated name can also be created at [geojson.io](https://geojson.io/#map=2/20.0/0.0) and stored in [`./data`](https://github.com/AdrienWehrle/earthspy/tree/main/data).\nIn this way, the name of the region can be directly passed to the `bounding_box`\nquery parameter. See below for a simple example with the [ilulissat.geojson](https://github.com/AdrienWehrle/earthspy/tree/main/data/ilulissat.geojson) example file.\n\n```python\nimport earthspy.earthspy as es\n\n# auth.txt should contain username and password (first and second row)\njob = es.EarthSpy(\"/path/to/auth.txt\")\n\n# as simple as it gets\njob.set_query_parameters(\n    bounding_box=\"Ilulissat\",\n    time_interval=[\"2019-08-03\", \"2019-08-10\"],\n    evaluation_script=\"https://custom-scripts.sentinel-hub.com/custom-scripts/sentinel-2/true_color/script.js\",\n    data_collection=\"SENTINEL2_L2A\",\n)\n\n# and off it goes!\njob.send_sentinelhub_requests()\n```\n\n\n# Operational Near Real-Time (NRT) deployment\n\n`earthspy` can be easily deployed for NRT monitoring. The setup is as simple as wrapping the query parameters in a short python script such as [earthspy_NRT.py](https://github.com/AdrienWehrle/earthspy/blob/main/earthspy/operational/earthspy_NRT.py) and including it in a cron job. See an example below where Sentinel-2 images of Ilulissat, Greenland acquired over the past three days are downloaded everyday at noon.\n```bash\n# m h  dom mon dow   command\n00 12 * * * /bin/bash -c \"/path/to/earthspy_NRT.py\" \u003e /path/to/log/log_earthspy_NRT.txt\n```\n\n# Documentation\n\nThe documentation of `earthspy` is hosted on [readthedocs](https://earthspy.readthedocs.io/en/latest/).\n\n# Contributing\n\nContributions to `earthspy` are more than welcome! Guidelines are\npresented in [CONTRIBUTING.md](https://github.com/AdrienWehrle/earthspy/blob/main/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwehrad%2Fearthspy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwehrad%2Fearthspy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwehrad%2Fearthspy/lists"}