un_energy_balance
Pack: un-energy · Connect: https://pipeworx.io/mcp (see Connect below for a single-pack URL)
No MCP client? Call it directly: GET https://gateway.pipeworx.io/v1/tools/un_energy_balance for the schema, then POST the same URL with its arguments for the data.
Country energy balance from the UN Statistics Division, always in terajoules (TJ): one product group (coal and peat, oil products, natural gas, electricity, total energy, …) against one flow (primary production, imports, exports, total energy supply, transformation, final consumption, …) for a year or range. Use for questions like “total natural gas supply of Egypt in 2023 in TJ” or “total coal supply in Israel 2020”. Coverage is annual, ~190 countries. Example: un_energy_balance({ country: “Israel”, commodity: “coal”, flow: “total energy supply”, year: 2020 }). Product groups here are broad; for one named fuel (aviation gasoline, kerosene, lignite) use un_energy_statistics.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
country | string | yes | Country name or UN M49 numeric code, e.g. “Egypt” or “818”. |
commodity | string | no | Product group, e.g. “natural gas”, “coal”, “oil products”, “electricity”, “total energy”. Words that match several groups return all of them. Omit for every group. |
flow | string | no | Balance flow, e.g. “total energy supply” (default), “primary production”, “imports”, “exports”, “final consumption”, “households”. Call un_energy_codes for the full list. |
year | number | no | A single year, e.g. 2023. |
start_year | number | no | First year of a range (ignored if year is set). |
end_year | number | no | Last year of a range (ignored if year is set). |
Example call
Arguments
{
"country": "Israel",
"commodity": "coal",
"flow": "total energy supply",
"year": 2020
}
curl
curl -X POST https://gateway.pipeworx.io/un-energy/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"un_energy_balance","arguments":{"country":"Israel","commodity":"coal","flow":"total energy supply","year":2020}}}'
TypeScript (@pipeworx/sdk)
import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();
const result = await pipeworx.call('un_energy_balance', {
"country": "Israel",
"commodity": "coal",
"flow": "total energy supply",
"year": 2020
});
Response shape
| Field | Type | Description |
|---|---|---|
country | string | |
country_code | string | |
count | number | |
rows | array | |
truncated | boolean | |
notes | string | |
source | string | |
retrieved_at | string |
Full JSON Schema
{
"type": "object",
"properties": {
"country": {
"type": "string"
},
"country_code": {
"type": "string"
},
"count": {
"type": "number"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"year": {
"type": "number"
},
"commodity": {
"type": "string"
},
"commodity_code": {
"type": "string"
},
"flow": {
"type": "string"
},
"flow_code": {
"type": "string"
},
"value_tj": {
"type": "number"
},
"unit": {
"type": "string"
},
"estimated": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"truncated": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"source": {
"type": "string"
},
"retrieved_at": {
"type": "string"
}
},
"additionalProperties": true
}
Connect
Add this to your MCP client config — every tool in the catalog, including this one — or use one-click install buttons:
{
"mcpServers": {
"pipeworx": {
"url": "https://pipeworx.io/mcp"
}
}
}
Connect to just the un-energy pack
{
"mcpServers": {
"un-energy": {
"url": "https://gateway.pipeworx.io/un-energy/mcp"
}
}
}
See Getting Started for client-specific install steps.