HESTIA Converters

Library to convert from/to the HESTIA format.

Quick start

Install the base library and the converter you need. Each converter is its own install extra, so you only pull the dependencies of the formats you use:

pip install hestia-earth-converters
pip install "hestia-earth-converters[SimaPro]"

hestia-convert --help is generated from the converters you installed, so it always lists exactly the formats and options available to you.

# a HESTIA ImpactAssessment, downloaded by id, as a SimaPro CSV
hestia-convert --output-folder out --input-format HESTIA --output-format SimaPro \
  --hestia-impact-id cocoaSeedWhole-ghana-2010-2025-20250916

# a file on disk, converted to HESTIA nodes
hestia-convert --output-folder out --input-format OpenLCA --output-format HESTIA \
  --input-file export.zip

Some data needs an API key, as does downloading any node with --hestia-impact-id. Create an account, copy the key from the "API Access" section of https://www.hestia.earth/profile, and set it as the API_ACCESS_TOKEN environment variable.

Where no converter goes straight from one format to another, the CLI runs the pair that does, by way of HESTIA. So every input format reaches LSRS:

hestia-convert --output-folder out --input-format Klim --output-format LSRS \
  --input-file farm.zip

runs Klim -> HESTIA, then HESTIA -> LSRS over what it wrote. The intermediate HESTIA files stay in --output-folder — they are output too, and they are what makes a chained run debuggable. --filter-by-name names a result of the first leg, and the rest of the chain sees only what it selected.

These flags apply to every conversion. Each converter adds more of its own, prefixed with its name; its README lists them.

Converters

Term mappings come from hestia-convert-flowmaps, downloaded automatically unless --mapping-files-directory points elsewhere. Errors and omissions in a mapping belong in an issue on that repository.

A run that had to drop a flow says so, and leaves you the list. What the flowmaps do not cover is written to missing-flowmaps.txt — one line per flow, deduplicated, with the name and unit the source states for it — and the run ends by naming that file and the issue tracker to attach it to. Nothing is written when everything mapped. --missing-flowmaps-file puts it somewhere else.

# 8 flow(s) this conversion could not map, and so dropped.
# conversion: FCC -> HESTIA
# flowmaps: 20260821-8550eee8
...
# direction	nomenclature	flow	name	unit
to HESTIA	FCC	proc_00141	On-farm processing (i.e. veg boxes) - Water ... - Mains water ...	m3

The file is a record of one run against one version of the flowmaps, so it is gitignored rather than committed.

Every run checks whether a newer version has been published and warns if so, naming the version in use and the current one. It does not download it: a flowmap version is part of what produced a result, so the same command keeps giving the same answer until you say otherwise. Pass --update-flowmaps to take the new version instead.

The check reads a single 18-byte file and is advisory only — if it cannot be reached, the conversion runs on what is already on disk. Only the default hestia-flowmaps folder is checked; a folder you name is yours, whether it is edited or deliberately pinned. The version in use is recorded in hestia-flowmaps/version.txt, so a folder assembled before that file existed reports as unrecorded until it is next downloaded.

Only the bundles your install needs are downloaded. The flowmaps are published per nomenclature, and each bundle belongs to an install extra — someone who installed [FCC] gets the four FCC maps rather than all 101, which is 40KB instead of 22MB compressed. The whole archive is still what you get when the extras cannot be worked out, such as a source checkout with nothing installed. To choose the set yourself:

python download_flowmaps.py --bundle fcc klim --version-filepath tests/flowmaps-version.txt

Bundles unpack into the same folder, so several combine. An unknown name is refused before anything downloads, and the published names are listed in the error.

Adding a converter? See CONVERTER_BLUEPRINT.md. Contributing? See CONTRIBUTING.md.