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

NameTypeRequiredDescription
countrystringyesCountry name or UN M49 numeric code, e.g. “Egypt” or “818”.
commoditystringnoProduct group, e.g. “natural gas”, “coal”, “oil products”, “electricity”, “total energy”. Words that match several groups return all of them. Omit for every group.
flowstringnoBalance flow, e.g. “total energy supply” (default), “primary production”, “imports”, “exports”, “final consumption”, “households”. Call un_energy_codes for the full list.
yearnumbernoA single year, e.g. 2023.
start_yearnumbernoFirst year of a range (ignored if year is set).
end_yearnumbernoLast 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

FieldTypeDescription
countrystring
country_codestring
countnumber
rowsarray
truncatedboolean
notesstring
sourcestring
retrieved_atstring
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.

Regenerated from source · build November 21, 2026