Metadata-Version: 2.4
Name: hestia_earth_earth_engine
Version: 0.6.2
Summary: Hestia's earth engine.
Home-page: https://gitlab.com/hestia-earth/hestia-earth-engine
Author: Hestia Team
Author-email: guillaume@hestia.earth
License: MIT
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hestia-earth-utils>=0.16.27
Requires-Dist: google-api-python-client>=2
Requires-Dist: earthengine-api
Provides-Extra: geopandas
Requires-Dist: shapely; extra == "geopandas"
Requires-Dist: geopandas; extra == "geopandas"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Hestia Earth Engine

[![Pipeline Status](https://gitlab.com/hestia-earth/hestia-earth-engine/badges/master/pipeline.svg)](https://gitlab.com/hestia-earth/hestia-earth-engine/commits/master)
[![Coverage Report](https://gitlab.com/hestia-earth/hestia-earth-engine/badges/master/coverage.svg)](https://gitlab.com/hestia-earth/hestia-earth-engine/commits/master)

Hestia's utilities to make queries to Earth Engine.

## Getting Started

1. Sign up for a [Google Cloud Account](https://cloud.google.com)
2. Enable the [Earth Engine API](https://developers.google.com/earth-engine)
3. Create a [Service Account with Earth Engine access](https://developers.google.com/earth-engine/guides/service_account)
4. Set the service account JSON credentials in the following file: `ee-credentials.json`
5. Set the following environment variable:
```
# path to the ee-credentials.json file saved at previous step
EARTH_ENGINE_KEY_FILE=./ee-credentials.json
```
6. The GADM assets are not shared publicly, as [GADM](https://gadm.org/license.html) cannot be redistributed. Download version 3.6 by level and upload each level to your own Earth Engine account, keeping the names `gadm36_0` to `gadm36_5`:
```bash
curl -O https://geodata.ucdavis.edu/gadm/gadm3.6/gadm36_levels_shp.zip
unzip gadm36_levels_shp.zip -d gadm36_levels
# the Earth Engine CLI uploads from Google Cloud Storage
gsutil cp gadm36_levels/gadm36_* gs://<your-bucket>/gadm36/
for level in 0 1 2 3 4 5; do
  earthengine upload table --asset_id=users/<your-account>/gadm36_$level gs://<your-bucket>/gadm36/gadm36_$level.shp
done
```
You can also upload each level from the Code Editor (Assets > New > Shape files), selecting its `.shp`, `.shx`, `.dbf` and `.prj` files. Then set the folder holding them:
```
# defaults to users/hestiaplatform
HESTIA_ASSETS=users/<your-account>
# optional, defaults to HESTIA_ASSETS
HESTIA_GADM_ASSETS=users/<your-account>
```

## Install

1. Install Python `3` (we recommend using Python `3.6` minimum)
2. Install the module:
```bash
pip install hestia_earth.earth_engine
```

### Usage

```python
from hestia_earth.earth_engine import init_gee, run

# call this only once during a session
init_gee()
# fetch sand content for a specific location
data = {
  "ee_type": "raster",
  "collections": [
    {
      "collection": "users/hestiaplatform/T_SAND",
      "fields": "first"
    }
  ],
  "coordinates": [
    {
      "latitude": -11.77,
      "longitude": -45.7689
    }
  ]
}
result = run(data)
assert result == [81]
```
