Tutorial: Climate TRACE (Carbon Emissions)

Environment

Data source: Climate TRACE (climatetrace.org)

Overview

Climate TRACE (Carbon Emissions) wraps Climate TRACE (climatetrace.org), handling authentication, pagination, and rate limits for you. This tutorial covers all 7 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-climate-trace": {
      "url": "https://context.gnist.ai/mcp/climate-trace/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (7)

`rank_countries_by_emissions`

Rank countries by greenhouse gas emissions. Uses Climate TRACE data covering 252 countries and 60+ greenhouse gases. Returns country rankings with total emissions and optional sector breakdowns. Args: gas: Gas type to rank by (default co2e_100yr). start: Start year filter. end: End year filter. sectors: Comma-separated sector filter. continent: Continent filter. Returns: Ranked list of countries with emissions totals.

Parameter	Type	Required	Description
`gas`	string	optional	Gas type: 'co2', 'co2e_20yr', 'co2e_100yr', 'ch4', 'n2o'. Default 'co2e_100yr'. (default: `co2e_100yr`)
`start`	any	optional	Start year (inclusive). Omit for all available years.
`end`	any	optional	End year (inclusive). Omit for all available years.
`sectors`	any	optional	Comma-separated sectors (e.g. 'power,transportation'). Omit for all sectors.
`continent`	any	optional	Continent filter: 'Africa', 'Asia', 'Europe', 'North America', 'Oceania', 'South America'.

curl -X POST "https://context.gnist.ai/mcp/climate-trace/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "rank_countries_by_emissions", "arguments": {"gas": "co2e_100yr"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/climate-trace/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'gas': 'co2e_100yr'},
            'name': 'rank_countries_by_emissions'}},
)
print(resp.json())

`search_emission_sources`

Search for top emission sources (facilities, power plants, etc.). Returns ranked emission sources with location, sector, and emissions data. Sources include power plants, factories, oil/gas facilities, and more. Args: year: Filter by emissions year. gas: Gas type (default co2e_100yr). sectors: Comma-separated sector filter. country: ISO country code filter. limit: Max results (1-100, default 20). Returns: List of emission sources with name, location, sector, and emissions.

Parameter	Type	Required	Description
`year`	any	optional	Emissions year (e.g. 2022). Omit for latest.
`gas`	string	optional	Gas type (default 'co2e_100yr'). (default: `co2e_100yr`)
`sectors`	any	optional	Comma-separated sectors (e.g. 'power,manufacturing').
`country`	any	optional	ISO country code (e.g. 'US', 'CHN', 'NOR').
`limit`	integer	optional	Number of results (1-100, default 20). (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/climate-trace/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_emission_sources", "arguments": {"year": "2022"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/climate-trace/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'year': '2022'}, 'name': 'search_emission_sources'}},
)
print(resp.json())

`get_emission_source`

Get detailed information for a specific emission source. Returns full details including time series emissions data for a single facility or source identified by its Climate TRACE source ID. Args: source_id: Climate TRACE source ID. Returns: Source details with name, location, sector, and emissions time series.

Parameter	Type	Required	Description
`source_id`	string	required	Climate TRACE source ID. Use search_emission_sources to find IDs.

curl -X POST "https://context.gnist.ai/mcp/climate-trace/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_emission_source", "arguments": {"source_id": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/climate-trace/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'source_id': '12345'}, 'name': 'get_emission_source'}},
)
print(resp.json())

`get_aggregate_emissions`

Get aggregate greenhouse gas emissions data. Returns total emissions aggregated by the specified filters — useful for comparing sectors, countries, or tracking emissions over time. Args: year: Filter by emissions year. gas: Gas type (default co2e_100yr). sectors: Comma-separated sector filter. country: ISO country code filter. Returns: Aggregated emissions data for the specified filters.

Parameter	Type	Required	Description
`year`	any	optional	Emissions year (e.g. 2022). Omit for latest.
`gas`	string	optional	Gas type (default 'co2e_100yr'). (default: `co2e_100yr`)
`sectors`	any	optional	Comma-separated sectors (e.g. 'power,transportation').
`country`	any	optional	ISO country code (e.g. 'US', 'CHN', 'DEU').

curl -X POST "https://context.gnist.ai/mcp/climate-trace/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_aggregate_emissions", "arguments": {"year": "2022"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/climate-trace/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'year': '2022'}, 'name': 'get_aggregate_emissions'}},
)
print(resp.json())

`list_emission_sectors`

List all available emission sectors in Climate TRACE. Returns the complete list of sectors used to categorize emission sources, such as power, transportation, manufacturing, agriculture, etc. Returns: List of all sector definitions.

curl -X POST "https://context.gnist.ai/mcp/climate-trace/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_emission_sectors", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/climate-trace/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_emission_sectors'}},
)
print(resp.json())

`list_emission_countries`

List all countries tracked by Climate TRACE. Returns the full list of 252 countries with emissions data available. Returns: List of all country definitions.

curl -X POST "https://context.gnist.ai/mcp/climate-trace/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_emission_countries", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/climate-trace/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_emission_countries'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/climate-trace/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/climate-trace/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_emission_sources to find items, then get_emission_source to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Climate TRACE (Carbon Emissions) provide?

Global greenhouse gas emissions data — country rankings, facility-level sources, sector breakdowns for CO2, CH4, N2O and 60+ gases covering 252 countries. It exposes 7 tools: rank_countries_by_emissions, search_emission_sources, get_emission_source, get_aggregate_emissions, list_emission_sectors, list_emission_countries, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Climate TRACE (Carbon Emissions) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 7 tools.

Getting Started with Climate TRACE (Carbon Emissions)