Skip to content
VoLCA Docs

Start with the HTTP API

Task

Section titled “Task”

Make an exact activity search and retrieve its inventory as JSON. This is the same BAFU / Electricity mix / CH / 1 kWh exercise as the CLI and Python paths.

Prerequisites

Section titled “Prerequisites”
  • curl and a terminal.
  • Complete steps 1 to 3 of the CLI exercise: install the released engine, download and check the public BAFU archive, and start the local server on 127.0.0.1:18765.
  • Leave your server terminal running. No hosted account or subscription is needed for this local exercise.

The API is an interface to a running engine, not a service made available merely by installing the Python library.

Action

Section titled “Action”

1. Check the engine

Section titled “1. Check the engine”
Terminal window
curl --fail-with-body http://127.0.0.1:18765/api/v1/version

For the pinned release, the response includes version: "0.12.0" and wireVersion: 14. Continue only when your own server has started and loaded BAFU.

2. Find the exact activity

Section titled “2. Find the exact activity”
Terminal window
curl --fail-with-body 'http://127.0.0.1:18765/api/v1/db/bafu-2026-v1/activities?name=Electricity%20mix&geo=CH&exact=true'

Check that total is 1, the location is CH, and the reference product unit is kWh. The exact match is:

3dd9f4d2-ebc3-32d6-8138-ba4253c4ebc3_a99c8f9b-0339-5c79-a622-08e1b5bee775

3. Save its inventory

Section titled “3. Save its inventory”
Terminal window
curl --fail-with-body 'http://127.0.0.1:18765/api/v1/db/bafu-2026-v1/activity/3dd9f4d2-ebc3-32d6-8138-ba4253c4ebc3_a99c8f9b-0339-5c79-a622-08e1b5bee775/inventory' -o inventory-api.json

Open the file in a text editor. Stop your own server with Ctrl+C when finished. These requests are read-only; the setup binds to loopback and does not expose a public unauthenticated API.

Expected result

Section titled “Expected result”

inventory-api.json contains metadata, flows and statistics. With the checked archive and engine, metadata.totalFlows is 2147, emissionFlows is 1795 and resourceFlows is 352. The CLI and HTTP API returned identical inventory JSON in the local check.

Individual flows carry quantities, units and compartments. This is a life-cycle inventory, not a characterized impact score. Do not add quantities across units or interpret raw magnitude as environmental importance.

Troubleshooting

Section titled “Troubleshooting”
  • Connection refused: start the server from the CLI setup and wait for readiness. Check the port in both terminal windows.
  • 404 or no database: verify the loaded database name and the full /api/v1/db/... path.
  • Search returns no unique match: stop and check the archive version and checksum rather than choosing a different activity.
  • 401/403 on a hosted engine: hosted authentication and permissions differ from this local example. Use the address of your engine and an authorized token through the supported flow. Never put credentials in a published script or URL.
  • --fail-with-body unavailable: upgrade curl or use --fail; check the exit status before treating the saved file as a result.

Next step

Section titled “Next step”

Read the HTTP API guide and generated reference. For typed results without manually parsing JSON, use pyvolca.