HESTIA Utils

Install

Install the module:

pip install hestia_earth.utils

Add this to your environment variables:

API_URL=https://api.hestia.earth
WEB_URL=https://www.hestia.earth

Usage

To download a file from the HESTIA API:

from hestia_earth.schema import SchemaType
from hestia_earth.utils.api import download_hestia

cycle = download_hestia('cycleId', SchemaType.CYCLE)
sandContent = download_hestia('sandContent', SchemaType.TERM)

To search for a specific Node on HESTIA:

from hestia_earth.schema import SchemaType
from hestia_earth.utils.api import find_node_exact

source = find_node_exact(SchemaType.SOURCE, {'bibliography.title': 'My Bibliography'})

To get a lookup table from local file system:

from hestia_earth.schema import SchemaType
from hestia_earth.utils.lookup import load_lookup

df = load_lookup('path/to/my/lookup.csv')

To get a lookup table from HESTIA:

from hestia_earth.schema import SchemaType
from hestia_earth.utils.lookup import download_lookup

df = download_lookup('crop.csv')

LSRS Format

You can use this library to convert HESTIA data into the LSRS format.

convert() accepts Impact Assessment, Cycle, Site and Source nodes and returns one simplified dict per node:

Impact Assessment → the 88 LSRS indicator columns plus metadata (including land transformation and deforestation read from its indicators).
Cycle → yield, EVS, seed, pesticide, diesel, electricity, crop residues, and (using the nutrient/unit helpers in lsrs/models_utils.py) fertiliser kg N / kg P2O5 / kg K2O, lime kg CaCO3 and irrigation m3.
Site → site type, country, region and current land cover.
Source → bibliography title and year.

These JSON outputs can be rendered to Excel or stored elsewhere. lsrs/models_utils.py holds nutrient/unit/land-cover helpers copied from hestia-earth-models so this library has no dependency on it.

For example, this will let you download all verified aggregation on HESTIA:

Add the env variable API_ACCESS_TOKEN and use the API Key from your account.
Create a file to store the search query:

{
  "bool": {
    "must": [
      { "match": { "@type": "ImpactAssessment" } },
      { "match": { "aggregatedDataValidated": true } }
    ]
  }
}

Run python3 convert_to_lsrs.py --query-path test.json --data-state recalculated

This will create 2 files:

query-results-lsrs.json: contains the raw JSON data needed to generate the Excel file
query-results-lsrs.xlsx: cotains the LSRS data in Excel format.

Note: if you make some changes to the Excel generation, you can run this to use the json data and re-generate the Excel file quicker: python3 render_lsrs.py --filepath query-results-lsrs.json

Converting multiple files and rendering into a single Excel

You can use the convert script to create all the JSON files containing the raw data, then render everything together at once:

Run all your conversion, using --skip-rendering parameter:

python3 convert_to_lsrs.py --query-path test1.json --data-state recalculated --skip-rendering
python3 convert_to_lsrs.py --query-path test1.json --data-state recalculated --skip-rendering

This will write multiple JSON files in the samples folder. Once done, render all together: python3 render_lsrs.py --folder samples. This will create the final samples.xlsx file.

Metadata

Release files for hestia-earth-utils 0.17.30

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hestia-earth-utils 0.17.30
File	Size	Uploaded
hestia_earth_utils-0.17.30.tar.gz	100.4 kB	Sep 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hestia-earth-utils 0.17.30
File	Interpreter	ABI	Platform	Reset
hestia_earth_utils-0.17.30-py3-none-any.whl 92.8 kB Sep 21, 2026	Python 3	none	any	Details

Total release size: 193.2 kB

Release files / hestia_earth_utils-0.17.30.tar.gz

Download URL	hestia_earth_utils-0.17.30.tar.gz
Size	100.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`fb913ce2ac75259340194d4a2648e01c974549486bbd21f98d2e59b47d3f3a17`
BLAKE2b-256 checksum How to use checksums	`501def4f8f39dddb5c9494c671973b5a132c70f0a8498b3ea93525386343b524`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / hestia_earth_utils-0.17.30-py3-none-any.whl

Download URL	hestia_earth_utils-0.17.30-py3-none-any.whl
Size	92.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4475f7763ab73772c8761934257486971dcb51025a68198d97c89a311ef11e63`
BLAKE2b-256 checksum How to use checksums	`a0e5907bb90cb396c4ab1ae731e57aaa35659a79e47f03b2958a582567c3f8ba`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`