The openLCA IPC Protocol

openLCA’s IPC server exposes the calculation engine through a network interface. Any language capable of sending HTTP requests and parsing JSON can connect to it. The Python olca-ipc package wraps this protocol in a convenience layer, but the protocol underneath is plain JSON-RPC 2.0 over HTTP. Understanding it directly opens openLCA to Fortran, R, Julia, MATLAB, JavaScript, C++, or anything else that can make a POST request.

This article covers JSON-RPC over HTTP, which is the default when starting the IPC server from the openLCA GUI and the protocol used by the Python and Fortran client examples. openLCA also supports gRPC and a REST API for other deployment scenarios, but these require different setup and are not covered here. gRPC offers higher performance and auto-generated client code for C++, Java, Go, C#, and Kotlin. The REST API is designed for web application integrations.

This article documents the JSON-RPC methods, their request and response formats, and includes working curl commands for testing. Everything here was verified against a live openLCA 2.6 IPC server.

Starting the server#

In openLCA, go to Tools > Developer Tools > IPC Server. Leave the port as 8080 and click the green play button. The server listens on http://localhost:8080 and accepts JSON-RPC 2.0 requests via HTTP POST.

How JSON-RPC works#

Every request follows the same structure:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "method/name",
    "params": { ... }
}

The id field is a sequence number you increment with each request. The server echoes it back in the response so you can match requests to responses. The method field tells openLCA what to do. The params object carries the input data for that method.

Every response comes back as:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": { ... }
}

If something goes wrong, the response contains error instead of result:

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {"code": -32601, "message": "Does not understand: invalid/method"}
}

Method reference#

The methods below are grouped by function. All were verified against a live openLCA 2.x IPC server using curl.

Data access methods#

These methods read from and write to the openLCA database.

data/get/descriptors#

Lists all entities of a given type as lightweight descriptors (name, ID, category).

Request:

{
    "jsonrpc": "2.0", "id": 1,
    "method": "data/get/descriptors",
    "params": {"@type": "ProductSystem"}
}

Response:

{
    "jsonrpc": "2.0", "id": 1,
    "result": [
        {
            "@type": "ProductSystem",
            "@id": "6250e70e-1878-41ff-91e0-4f2fdae3a3ea",
            "name": "Production of composite part - US",
            "category": "composite part product systems"
        }
    ]
}

Common type values: ProductSystem, ImpactMethod, Process, Flow, Parameter, FlowProperty, UnitGroup.

data/get/descriptor#

Gets a single descriptor by type and name or ID.

Request (by name):

{
    "jsonrpc": "2.0", "id": 2,
    "method": "data/get/descriptor",
    "params": {"@type": "Process", "name": "Product manufacture"}
}

Response:

{
    "jsonrpc": "2.0", "id": 2,
    "result": {
        "@type": "Process",
        "@id": "5656abb3-d888-4a87-a4eb-8d44abc5155c",
        "name": "Product manufacture"
    }
}

The params object accepts @id for lookup by UUID or name for lookup by name. Both can be provided together.

data/get#

Gets the full entity object by type and ID. The response includes all fields: exchanges, parameters, documentation, allocation factors, and everything else stored on that entity.

Request:

{
    "jsonrpc": "2.0", "id": 3,
    "method": "data/get",
    "params": {
        "@type": "ProductSystem",
        "@id": "6250e70e-1878-41ff-91e0-4f2fdae3a3ea"
    }
}

The response is the complete JSON representation of the entity. For a process, this includes all exchanges with amounts, units, providers, uncertainty distributions, and pedigree entries. For a product system, it includes the process links and target amount configuration.

data/get/parameters#

Gets the parameters relevant to a specific process or product system.

Request:

{
    "jsonrpc": "2.0", "id": 4,
    "method": "data/get/parameters",
    "params": {
        "@type": "ProductSystem",
        "@id": "6250e70e-1878-41ff-91e0-4f2fdae3a3ea"
    }
}

Response:

{
    "jsonrpc": "2.0", "id": 4,
    "result": [
        {"name": "infrastructure_lifetime", "value": 15.0, "isProtected": false},
        {"name": "electricity_kwh", "value": 200.0, "isProtected": false}
    ]
}

For product systems, the response includes all parameters that can be overridden in a calculation setup. These are the parameter names and values that feed into the parameters array of result/calculate.

data/get/providers#

Lists all technology flow providers in the database.

Request:

{
    "jsonrpc": "2.0", "id": 5,
    "method": "data/get/providers",
    "params": {}
}

Response:

{
    "jsonrpc": "2.0", "id": 5,
    "result": [
        {
            "provider": {"@type": "Process", "@id": "...", "name": "..."},
            "flow": {"@type": "Flow", "@id": "...", "name": "..."}
        }
    ]
}

An optional @id for a specific flow can be included in params to filter providers for that flow.

Calculation methods#

These methods run calculations and retrieve results. The lifecycle is: calculate, wait for readiness, retrieve results, dispose.

result/calculate#

Runs a calculation. The request takes a product system, an impact method, and optionally a list of parameter overrides. The calculation starts asynchronously.

Request (basic):

{
    "jsonrpc": "2.0", "id": 6,
    "method": "result/calculate",
    "params": {
        "target": {
            "@type": "ProductSystem",
            "@id": "6250e70e-1878-41ff-91e0-4f2fdae3a3ea"
        },
        "impactMethod": {
            "@type": "ImpactMethod",
            "@id": "ee579ea6-1a3a-39a9-9db2-dd07847af6b2"
        }
    }
}

Request (with parameter overrides for scenario calculations):

{
    "jsonrpc": "2.0", "id": 6,
    "method": "result/calculate",
    "params": {
        "target": {
            "@type": "ProductSystem",
            "@id": "6250e70e-1878-41ff-91e0-4f2fdae3a3ea"
        },
        "impactMethod": {
            "@type": "ImpactMethod",
            "@id": "ee579ea6-1a3a-39a9-9db2-dd07847af6b2"
        },
        "parameters": [
            {"name": "infrastructure_lifetime", "value": 25.0}
        ]
    }
}

The parameters array contains one object per parameter to override. Each object needs a name and value. For parameters that belong to a specific process (local parameters), a context field can be added with the process type and ID.

Response:

{
    "jsonrpc": "2.0", "id": 6,
    "result": {
        "@id": "32ce40c4-20ac-419e-90ec-f04b09ea175a",
        "isReady": false,
        "isScheduled": true,
        "time": 1788309857964
    }
}

The result @id is a handle to this calculation’s results on the server. It is needed for all subsequent result methods.

result/state#

Polls whether a calculation has finished.

Request:

{
    "jsonrpc": "2.0", "id": 7,
    "method": "result/state",
    "params": {"@id": "32ce40c4-20ac-419e-90ec-f04b09ea175a"}
}

Response (finished):

{
    "jsonrpc": "2.0", "id": 7,
    "result": {
        "@id": "32ce40c4-20ac-419e-90ec-f04b09ea175a",
        "isReady": true,
        "isScheduled": false,
        "time": 1788309887856
    }
}

Client code polls this in a loop with a short delay until isReady is true, then proceeds to retrieve results.

result/total-impacts#

Retrieves the calculated impact results once result/state has returned isReady: true.

Request:

{
    "jsonrpc": "2.0", "id": 8,
    "method": "result/total-impacts",
    "params": {"@id": "32ce40c4-20ac-419e-90ec-f04b09ea175a"}
}

Response:

{
    "jsonrpc": "2.0", "id": 8,
    "result": [
        {
            "impactCategory": {
                "@type": "ImpactCategory",
                "@id": "6cd38f2b-5e49-3163-b563-e5eb815d8053",
                "name": "Global Warming",
                "category": "ReCiPe 2016 - Midpoint/H",
                "refUnit": "kg CO2eq"
            },
            "amount": 123.456
        }
    ]
}

The result is an array with one entry per impact category.

result/dispose#

Frees the calculation result on the server. Calling this after each calculation prevents the server from accumulating results in memory.

Request:

{
    "jsonrpc": "2.0", "id": 9,
    "method": "result/dispose",
    "params": {"@id": "32ce40c4-20ac-419e-90ec-f04b09ea175a"}
}

Response:

{
    "jsonrpc": "2.0", "id": 9,
    "result": {"@id": "32ce40c4-20ac-419e-90ec-f04b09ea175a"}
}

Additional result methods#

The Python olca-ipc source reveals further result methods. These have not been verified via curl but follow the same request pattern (pass {"@id": "result-id"} plus any additional parameters):

Contribution analysis:

• result/impact-contributions-of – impact contributions by tech flow
• result/direct-impacts-of – direct impacts of a specific tech flow
• result/total-impacts-of – total upstream impacts of a tech flow
• result/upstream-impacts-of – upstream impact tree traversal
• result/flow-contributions-of – flow contributions by tech flow

Inventory results:

• result/total-flows – total elementary flow results
• result/direct-interventions-of – direct elementary flows of a tech flow
• result/total-interventions-of – total elementary flows of a tech flow

Normalisation and weighting:

• result/total-impacts/normalized – normalised impact results
• result/total-impacts/weighted – weighted impact results

Cost results:

• result/total-costs – total cost result
• result/direct-costs-of – direct costs of a tech flow
• result/total-costs-of – total costs of a tech flow

Other:

• result/tech-flows – list all tech flows in the result
• result/envi-flows – list all elementary flows in the result
• result/impact-categories – list impact categories in the result
• result/demand – get the demand (functional unit) of the result
• result/sankey – generate Sankey graph data
• result/simulate – start Monte Carlo simulation
• result/simulate/next – run next Monte Carlo iteration

The calculation lifecycle#

A complete calculation follows five steps in order:

1. Call data/get/descriptors to find the product system and impact method UUIDs.
2. Call result/calculate with those UUIDs and any parameter overrides. Store the result @id.
3. Poll result/state until isReady is true.
4. Call result/total-impacts (or any other result method) to retrieve the numbers.
5. Call result/dispose to free server memory.

Steps 2 through 5 repeat for each calculation. Step 1 only needs to run once per session since the UUIDs are stable within a database.

For scenario calculations, data/get/parameters provides the parameter names and current values for a product system. These names go into the parameters array of result/calculate with overridden values.

The @ naming convention#

openLCA’s JSON uses @id and @type as field names. The @ prefix comes from JSON-LD conventions. Some JSON libraries treat @ as a special character in path expressions. A library using JSONPath or a similar path syntax may interpret result.@id as a JSONPath operator, returning the array index instead of the UUID.

The workaround is to navigate to the parent object first, then retrieve the @id child by literal name. Alternatively, since the @id UUID always appears as "@id":" followed by a 36-character string in the raw JSON, simple string matching works reliably.

Using curl for debugging#

curl is a command-line tool for making HTTP requests. It ships with macOS, Linux, and Windows 10 onwards.

The curl commands in this article are a diagnostic tool for any language. If your code produces unexpected results, running the same request from curl isolates whether the issue is in your code’s JSON handling or in the request format.

On Linux and macOS, curl commands use single quotes around the JSON body:

curl -s -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"data/get/descriptors","params":{"@type":"ProductSystem"}}'

On Windows CMD, use escaped double quotes on a single line:

curl -s -X POST http://localhost:8080 -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"data/get/descriptors\",\"params\":{\"@type\":\"ProductSystem\"}}"

On Windows PowerShell, use curl.exe (PowerShell aliases curl to Invoke-WebRequest):

curl.exe -s -X POST http://localhost:8080 -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"data/get/descriptors\",\"params\":{\"@type\":\"ProductSystem\"}}"

A common debugging sequence:

1. Send data/get/descriptors for ProductSystem to verify the server is responding.
2. Compare the @id values in the descriptor response against the ones your code sends to result/calculate.
3. Look at the raw response from result/calculate: a valid response contains an @id in the result object. An error response means the calculation setup was rejected.
4. Send result/state manually: if isReady stays false, the calculation may be stuck or the product system may have linking issues.

Quick reference#

Verified methods with params format:

Method	Params	Returns
data/get/descriptors	{"@type": "ProductSystem"}	Array of descriptors
data/get/descriptor	{"@type": "Process", "name": "..."}	Single descriptor
data/get	{"@type": "ProductSystem", "@id": "..."}	Full entity object
data/get/parameters	{"@type": "ProductSystem", "@id": "..."}	Array of parameters
data/get/providers	{}	Array of tech flows
result/calculate	{"target": {...}, "impactMethod": {...}}	{"@id": "...", "isReady": false}
result/calculate (scenarios)	Above + "parameters": [{"name": "...", "value": ...}]	Same as above
result/state	{"@id": "result-id"}	{"@id": "...", "isReady": true/false}
result/total-impacts	{"@id": "result-id"}	Array of impact values
result/dispose	{"@id": "result-id"}	{"@id": "..."}

Further reading#

The openLCA IPC tools repositories on GitHub contain working examples in Python and Fortran. The full method list in the Python client source is in olca-ipc on GitHub.

The rest of the openLCA scripting knowledge base covers connecting with Python, working with parameters, running scenario calculations, sensitivity analysis, and a Fortran batch calculator.