co2_emissions

Instructions

Implementation Reference

• src/index.js:113-163 (handler)

  Complete tool registration and handler for 'co2_emissions'. Fetches real-time CO2 emission intensity from Danish electricity production via Energi Data Service API (CO2Emis dataset). Processes data by price area, calculates averages, and classifies emission levels (clean/moderate/high).

  server.tool(
    "co2_emissions",
    "Get real-time CO2 emission intensity of Danish electricity production (g CO2/kWh). Updated every 5 minutes. Useful for timing energy-intensive tasks to low-carbon periods.",
    {
      area: z.string().optional().describe("Price area: DK1 or DK2, or a city/region name. Default: both areas."),
      hours: z.number().optional().describe("Hours of history to return (default: 1, max: 24)"),
    },
    async ({ area, hours = 1 }) => {
      const priceArea = area ? resolvePriceArea(area) : null;
      const filter = priceArea ? JSON.stringify({ PriceArea: priceArea }) : undefined;
      const limit = Math.min(hours * 12, 288) * (priceArea ? 1 : 2); // 12 readings/hour (5min intervals)
  
      const data = await fetchDataset("CO2Emis", {
        limit,
        sort: "Minutes5DK desc",
        filter,
      });
  
      if (!data.records?.length) {
        return { content: [{ type: "text", text: "No CO2 emission data available." }] };
      }
  
      const byArea = {};
      for (const r of data.records) {
        if (!byArea[r.PriceArea]) byArea[r.PriceArea] = [];
        byArea[r.PriceArea].push(r);
      }
  
      let output = "# Danish CO2 Emission Intensity\n\n";
      for (const [areaCode, records] of Object.entries(byArea)) {
        const latest = records[0];
        const values = records.map(r => r.CO2Emission).filter(v => v != null);
        const avg = values.length ? values.reduce((a, b) => a + b, 0) / values.length : null;
  
        output += `## ${areaCode} — ${PRICE_AREAS[areaCode] || areaCode}\n\n`;
        output += `**Current:** ${latest.CO2Emission} g CO2/kWh (${latest.Minutes5DK?.replace("T", " ").slice(0, 16)})\n`;
        if (avg != null) output += `**Average (last ${hours}h):** ${avg.toFixed(0)} g CO2/kWh\n`;
  
        // Classify
        const co2 = latest.CO2Emission;
        let label = "🟢 Very clean";
        if (co2 > 300) label = "🔴 High emissions";
        else if (co2 > 200) label = "🟡 Moderate";
        else if (co2 > 100) label = "🟢 Clean";
        output += `**Status:** ${label}\n\n`;
      }
  
      output += "*Source: Energi Data Service (Energinet). Real-time 5-minute resolution.*\n";
      return { content: [{ type: "text", text: output }] };
    }
  );

• src/index.js:117-119 (schema)

  Zod schema defining input parameters for co2_emissions tool: optional 'area' (price area string) and optional 'hours' (number, defaults to 1, max 24).

    area: z.string().optional().describe("Price area: DK1 or DK2, or a city/region name. Default: both areas."),
    hours: z.number().optional().describe("Hours of history to return (default: 1, max: 24)"),
  },

• src/index.js:16-28 (helper)

  fetchDataset helper function that constructs API URL, sets parameters, makes HTTP request to Energi Data Service API, and returns JSON response. Used by co2_emissions to fetch from 'CO2Emis' dataset.

  async function fetchDataset(dataset, params = {}) {
    const url = new URL(`${BASE_URL}/${dataset}`);
    url.searchParams.set("format", "json");
    for (const [k, v] of Object.entries(params)) {
      if (v != null) url.searchParams.set(k, String(v));
    }
    const res = await fetch(url.toString(), { headers: { "User-Agent": USER_AGENT } });
    if (!res.ok) {
      const text = await res.text();
      throw new Error(`Energi Data Service API error (${res.status}): ${text}`);
    }
    return res.json();
  }

• src/index.js:37-46 (helper)

  resolvePriceArea helper function that maps user input (DK1/DK2 codes or city/region names) to valid price area codes. Used by co2_emissions to resolve the 'area' parameter.

  function resolvePriceArea(input) {
    if (!input) return null;
    const upper = input.toUpperCase().trim();
    if (upper === "DK1" || upper === "DK2") return upper;
    const lower = input.toLowerCase().trim();
    // Map common regions
    if (["west", "western", "jylland", "jutland", "fyn", "funen", "esbjerg", "aarhus", "aalborg", "odense", "herning", "vejle", "kolding", "horsens", "randers", "viborg", "silkeborg"].includes(lower)) return "DK1";
    if (["east", "eastern", "sjælland", "zealand", "copenhagen", "københavn", "amager", "roskilde", "helsingør", "hillerød", "næstved", "køge", "lolland", "falster", "bornholm"].includes(lower)) return "DK2";
    return null;
  }