# ADEME Emission Factors – French Carbon Calculator (`shadow-tools/ademe-emission-factors`) Actor

Search ADEME Base Carbone emission factors (France), look them up by id, or compute kgCO2e for a list of activities. Unofficial, open data, AI-agent friendly.

- **URL**: https://apify.com/shadow-tools/ademe-emission-factors.md
- **Developed by:** [Shadow Tools](https://apify.com/shadow-tools) (community)
- **Categories:** Business, Developer tools, AI
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 carbon records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## ADEME Emission Factors – French Carbon Calculator

Call this Actor to get **French ADEME carbon emission factors** (kgCO2e per kWh, litre, km, kg...) or to **compute the kgCO2e of a list of activities** (quantity x factor). Use it when an AI agent or a human needs a sourced French emission factor or a first-pass footprint; do not use it for non-French factor sets or audited regulatory reports.
One call = one answer: `search` (find factors), `lookup` (fetch known ids), `calculate` (kgCO2e per line plus a total). No API key, typical run a few seconds.

> **Unofficial tool.** Not affiliated with, endorsed or maintained by ADEME. It reads the public ADEME open data (Base Carbone / Base Empreinte) and returns it as clean JSON.

#### Minimal input per mode

| Mode | Minimal input | What comes back |
|---|---|---|
| `search` | `{"mode": "search", "query": "TGV", "maxResults": 5}` | factor records (`factorId`, `name`, `value`, `unit`, `status`, `dataAsOf`, `attribution`...) |
| `lookup` | `{"mode": "lookup", "factorIds": ["28153"]}` | the factors with these ids, any status |
| `calculate` | `{"mode": "calculate", "lines": [{"factorId": "28153", "quantity": 1200, "unit": "passager.km"}]}` | one `calculation-line` per line (`kgCO2e`, `kgCO2eLow/High`, `factor`, `warnings`) + one `calculation-total` |

Short output (real run, 5 Nov 2026), `calculate` line above: `{"recordType": "calculation-line", "status": "ok", "kgCO2e": 3.036, "kgCO2eLow": 2.4288, "kgCO2eHigh": 3.6432, "factor": {"factorId": "28153", "name": "TGV", "value": 0.00253, "unit": "kgCO2e/passager.km"}, "dataAsOf": "2025-07-03", "datasetVersion": "V23.6"}`.

#### For AI agents (MCP)

- **One call = one answer.** Keep `maxResults` small (default 20; 5 is enough to pick a factor). Raise it only when the run SUMMARY says `capped: true`.
- **Find the id first, then compute.** For anything that matters: `search`, read `factorId` and `unit`, then `calculate` with `factorId` and a compatible unit. Text `item` matching can pick an unexpected factor (the line then carries a warning and up to 3 `alternatives`).
- **Errors fail fast** in the form `Field X invalid: expected Y, got Z, example W` (for example `Field location invalid: expected one of France continentale | Outre-mer | Europe | Monde | Autre pays du monde ...`). Fix that field and call again; no record is charged.
- **0 results is not an error.** The run succeeds with an empty dataset, and the key-value store record `SUMMARY` carries `note: "0 results: <reason / how to widen the search>"`. For `lookup`, unknown ids are listed in `notFound`. A truncated search sets `capped: true` plus a `note`.
- **Unit mismatches never guess**: a line with an incompatible unit gets `status: "unit_mismatch"`, no value and a warning, and the total says `complete: false`.

Three modes:

| Mode | You give | You get |
|---|---|---|
| `search` | words (French or English), category, unit, area, validity year, modified date | matching emission factors |
| `lookup` | a list of ADEME factor ids | the factors (any status, archived ones are flagged) |
| `calculate` | lines `{item or factorId, quantity, unit}` | kgCO2e per line (with low/high range, factor used, warnings) + one total record |

No API key, no account at ADEME, no proxy. Typical run: a few seconds.

### Who uses it

- **Sustainability / CSR teams and consultants** building a quick carbon estimate (energy, fuel, travel, purchases) with a traceable ADEME factor behind every number.
- **Developers and AI agents** that need French emission factors in JSON (call the Actor from an LLM agent; the `calculate` mode refuses silent unit guesses).
- **Spreadsheets and BI**: export factors (name, value, unit, uncertainty, validity) to CSV/Excel with one run.
- **Eco-design and procurement** comparing the footprint of fuels, electricity, transport modes or materials.
- **Finance and reporting tools**: add a first-pass kgCO2e column (with low/high range) to lists of activities such as fuel, kWh or passenger-km, then verify the factors before any audited report.
- **Teaching and training**: show students where a factor comes from, its unit, its uncertainty and its validity period.

### Quick start

**1. Search (French or English words)**

```json
{ "mode": "search", "query": "gaz naturel", "maxResults": 20 }
```

```json
{ "mode": "search", "query": "TGV", "category": "ferroviaire", "location": "France continentale" }
```

```json
{ "mode": "search", "unit": "kgCO2e/kWh", "validityYear": 2024, "includeGases": true, "maxResults": 100 }
```

**2. Look up by id**

```json
{ "mode": "lookup", "factorIds": ["13515", "28153"] }
```

**3. Calculate**

```json
{
  "mode": "calculate",
  "lines": [
    { "item": "gazole", "quantity": 300, "unit": "litre", "label": "Company van fuel" },
    { "factorId": "28153", "quantity": 1200, "unit": "passager.km", "label": "Business trips by TGV" },
    { "item": "gaz naturel", "quantity": 10, "unit": "kg", "label": "Boiler (wrong unit on purpose)" }
  ]
}
```

Call it from the API (replace `<user>`):

```bash
curl -X POST "https://api.apify.com/v2/acts/<user>~ademe-emission-factors/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"search","query":"gaz naturel","maxResults":5}'
```

### Input

| Field | Mode | Meaning |
|---|---|---|
| `mode` | all | `search` (default), `lookup`, `calculate` |
| `query` | search | Words that must all appear (name, attribute, tags, category; French **and** English fields are indexed). Accents/case ignored; no typo correction. |
| `category` | search | Words that must appear in the ADEME category path |
| `unit` | search | Exact French unit, e.g. `kgCO2e/kWh`, `kgCO2e/litre`, `kgCO2e/passager.km` |
| `location` | search | Mainland France, Overseas France, Europe, World, Other countries |
| `validityYear`, `modifiedSince` | search | Text match on the validity period (free text in the source); modified on/after `YYYY-MM-DD` |
| `includeArchived` | search | Also return archived (old) factors; default only valid ones |
| `includeGases` | search/lookup | Add per-gas values when published |
| `factorIds` | lookup | ADEME element ids |
| `lines` | calculate | Up to 500 lines |
| `maxResults` | search | 1–1000, default 20 |

An empty input `{}` returns 20 valid factors.

### Output example (real run, 5 Nov 2026)

`search` → one record (nulls removed):

```json
{
  "recordType": "factor",
  "factorId": "28153",
  "name": "TGV",
  "nameEn": "High Speed Train",
  "attribute": "2018",
  "category": "Transport de personnes > Ferroviaire > France continentale > TGV",
  "value": 0.00253,
  "unit": "kgCO2e/passager.km",
  "uncertaintyPct": 20,
  "status": "Valide générique",
  "location": "France continentale",
  "validityPeriod": "avr-21",
  "modifiedAt": "2021-12-15",
  "source": "InfoGES SNCF",
  "datasetVersion": "V23.6",
  "dataAsOf": "2025-07-03",
  "attribution": "Source: ADEME, Base Carbone® (Base Empreinte®) V23.6, data.ademe.fr, data as of 2025-07-03. Licence Ouverte / Open Licence (Etalab). Retrieved 2026-11-05 by an unofficial tool; not endorsed by ADEME."
}
```

`calculate` → one record per line plus a `calculation-total` record. Line 2 above (TGV, 1200 passenger-km): `kgCO2e: 3.036`, range `2.4288 – 3.6432`. Line 3 (natural gas asked in **kg** but the factor is per **kWh PCI**):

```json
{
  "recordType": "calculation-line", "line": 3, "status": "unit_mismatch",
  "warnings": ["Unit mismatch: you gave \"kg\" but this factor is expressed per \"kWh PCI\" (kgCO2e/kWh PCI). No value computed."],
  "factor": { "factorId": "13515", "name": "Gaz naturel", "value": 0.243, "unit": "kgCO2e/kWh PCI" }
}
```

The total record (`totalKgCO2e`, `totalTonnesCO2e`, `totalKgCO2eLow/High`, `linesComputed`, `linesNotComputed`, `complete`, `warnings`) only sums lines that were computed and says so when some were skipped.

### How the calculator behaves (read this)

- `kgCO2e = quantity × factor value`, after unit conversion **inside one dimension only**: kg/g/t, Wh/kWh/MWh/GWh/MJ/GJ, m/km, mL/L/m³, kg.km/t.km. Anything else (kg vs kWh, km vs passenger.km…) gives **no value** and a warning — never a guess.
- With `item` (text), the best text match **with a compatible unit** is used, and a mainland-France factor is preferred when scores are close. Text matching can pick an unexpected factor (e.g. "électricité" has hundreds of variants): the line carries a warning and up to 3 `alternatives`. For anything that matters, search first and pass the `factorId`.
- `Valide générique` factors are standard references; `Archivé` ones are old versions (flagged in the line warnings).
- Gas factors are often per **kWh PCI**; gas invoices are usually in PCS. The line warns you to check the basis.
- Uncertainty is ADEME's percentage per factor; the total combines lines in quadrature (independent factors assumed) — indicative only.

### Data, licence and attribution

- Source: ADEME **Base Carbone®** (Base Empreinte®) on `data.ademe.fr` (dataset `base-carboner`, currently V23.6, data as of 2025-07-03 at the time of writing; the run reports the current version and date in `datasetVersion` / `dataAsOf`).
- Licence: **Licence Ouverte / Open Licence (Etalab)** as stated on the dataset page. Attribution is included in every record (`attribution`). Base Carbone® and Base Empreinte® are ADEME trademarks; this tool is not endorsed by ADEME.
- Only factor rows are returned (the detail rows per emission category are ignored). The `Source`, `Programme`, `Contributeur` fields name organisations/programmes. E-mail addresses found in source comments are removed.
- Language: factor names exist in French (always) and English (most); searching works with both. Spanish fields are not returned.

### Privacy / GDPR by design

This Actor is deliberately built **not** to handle personal data of natural persons. This is a design choice made to respect the GDPR.

- It returns emission factor data only (ADEME Base Carbone): statistical and product data about activities, places and organisations. Your `lines` are plain activities and quantities; no personal data is asked for.
- E-mail addresses found in the source comments are replaced by `[email removed]`.
- Not guaranteed: the factor texts come from the open ADEME database and are passed through otherwise unchanged, so an occasional name in a source label cannot be excluded. You remain responsible for your own use of the data.
- The Actor stores nothing about you beyond your run's own dataset and logs on Apify.

### Related Actors

No direct overlap with the other Actors of this publisher. If you work with French public data, see [Product Recalls (RappelConso + Safety Gate)](https://apify.com/shadow-tools/eu-france-product-recalls) and [French Public Contract Awards (DECP)](https://apify.com/shadow-tools/french-public-procurement-awards-decp).

### Limits and disclaimer

- Unofficial tool, not affiliated with ADEME. Data are provided as is, without warranty. For regulatory or audited carbon reports (BEGES, CSRD…), check each factor and its conditions of use on the official Base Empreinte site; this Actor is a convenient way to query the data, not a certified calculator.
- Data freshness = the ADEME dataset version (`dataAsOf`); factors are updated by ADEME a few times a year.
- The ADEME API has no key, but is shared infrastructure: runs retry politely on HTTP 429/5xx. Large runs stop before the platform timeout and return partial results (`partial` in the run SUMMARY).
- Only the Base Carbone dataset is covered (not Agribalyse's separate datasets, nor Base Empreinte’s other data).

### Pricing

Pay per event, no subscription:

| Event | Price | Per 1,000 |
|---|---|---|
| `carbon-record`: one emission factor, one calculation line, or one calculation total delivered | **0.003 USD** | **3 USD per 1,000 records** |
| Actor start (once per run) | 0.00005 USD | n/a |

Examples: `search` returning 20 factors = 20 records = 0.06 USD; a `calculate` run with 10 lines = 10 line records + 1 total = 11 records = 0.033 USD (plus the tiny start event).

You can cap spend per run with the platform's **Maximum cost per run** setting: the Actor reads it, stops cleanly when the cap is reached and returns the partial results it already delivered (the run needs a cap high enough for at least one record, otherwise it stops with a clear error and nothing is charged). In `calculate` mode one record is kept for the total, so the cap must allow at least 2 records.

### Français (court)

Facteurs d'émission officiels de la Base Carbone® de l'ADEME : recherche (mots français ou anglais), consultation par identifiant et calcul simple de bilan (quantité × facteur, avec incertitude et avertissement si l'unité ne correspond pas). Outil non officiel, données sous Licence Ouverte, aucune donnée personnelle.

# Actor input Schema

## `mode` (type: `string`):

Pick one. "search" = use when you do not know the factor id and want to find emission factors by words/category/unit (needs query or other filters; returns factor records). "lookup" = use when you already have ADEME ids (factorIds, e.g. \["28153"]) and want those exact factors. "calculate" = use when you have activities with quantities (lines) and want kgCO2e per line plus a total. Allowed values: search, lookup, calculate. Default: search.

## `query` (type: `string`):

Search mode: words that must all appear in the factor (name, attribute, tags, category), French or English, e.g. "gaz naturel", "natural gas", "TGV", "electricity". Format: plain text, accents and case ignored, typos not corrected. Empty = no text filter (returns the first factors).

## `category` (type: `string`):

Search mode: words that must appear in the ADEME category path, e.g. "Transport de personnes ferroviaire" or "Combustibles". Format: plain text. Empty = any category.

## `unit` (type: `string`):

Search mode: keep only factors whose unit is exactly this French ADEME unit string, e.g. "kgCO2e/kWh", "kgCO2e/litre", "kgCO2e/passager.km", "kgCO2e/kg de poids net", "kgCO2e/t.km". Empty = any kgCO2e unit.

## `location` (type: `string`):

Search mode: keep only factors for this ADEME geographic area. Allowed values: France continentale, Outre-mer, Europe, Monde, Autre pays du monde (exact spelling, example: "France continentale"). Empty = all areas.

## `validityYear` (type: `integer`):

Search mode: keep factors whose validity period mentions this 4-digit year (1990-2100), e.g. 2024. The period is free text in the source, so this is a text match.

## `modifiedSince` (type: `string`):

Search mode: keep factors last modified on or after this date. Format YYYY-MM-DD, example: 2024-01-01. An invalid date makes the run fail with a clear error.

## `includeArchived` (type: `boolean`):

Search mode: by default only valid factors (generic or specific) are returned; set true to also get archived ones (old versions). Lookup mode always returns the status of each id. Example: true.

## `includeGases` (type: `boolean`):

Search/lookup modes: set true to add the per-gas values (CO2 fossil, CH4, N2O, biogenic CO2...) when ADEME publishes them. Default false (shorter records).

## `factorIds` (type: `array`):

Lookup mode (required there): list of 1 or more ADEME element identifiers as strings of digits, e.g. \["34722", "28153"] (34722 = electricity, mainland France). Ids come from the search output field factorId.

## `lines` (type: `array`):

Calculate mode (required there): list of 1 to 500 objects (see the example in the prefilled value) {"item": "gaz naturel" OR "factorId": "13515", "quantity": 1000 (number >= 0), "unit": "kWh", "location": optional area, "label": optional text}. Each line needs item or factorId, and quantity and unit are mandatory. With "item" the best match having a compatible unit is used and a warning asks you to check it; with "factorId" the factor is exact. Units are converted only inside kg/t, Wh/kWh/MWh/GJ, m/km, mL/L/m3, kg.km/t.km; any other mismatch gives no value and a warning (never a guess). Example: \[{"item": "gazole", "quantity": 300, "unit": "litre"}].

## `maxResults` (type: `integer`):

Search mode: maximum number of factors returned, integer 1-1000, default 20 (keep it small, e.g. 20; raise only if the run SUMMARY says capped). Your run cost cap may lower it.

## Actor input object example

```json
{
  "mode": "search",
  "query": "electricité",
  "includeArchived": false,
  "includeGases": false,
  "factorIds": [
    "34722",
    "28153"
  ],
  "lines": [
    {
      "item": "électricité",
      "quantity": 5000,
      "unit": "kWh",
      "location": "France continentale",
      "label": "Office electricity"
    },
    {
      "item": "gazole",
      "quantity": 300,
      "unit": "litre",
      "label": "Company van fuel"
    },
    {
      "item": "TGV",
      "quantity": 1200,
      "unit": "passager.km",
      "label": "Business trips by train"
    }
  ],
  "maxResults": 20
}
```

# Actor output Schema

## `factors` (type: `string`):

Factor name, value, unit, uncertainty, status, validity and source (search and lookup modes).

## `calculation` (type: `string`):

kgCO2e per line with the factor used, warnings, and a final total record (calculate mode).

## `dataset` (type: `string`):

Every field of every record, downloadable as JSON, CSV or Excel.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "electricité",
    "lines": [
        {
            "item": "électricité",
            "quantity": 5000,
            "unit": "kWh",
            "location": "France continentale",
            "label": "Office electricity"
        },
        {
            "item": "gazole",
            "quantity": 300,
            "unit": "litre",
            "label": "Company van fuel"
        },
        {
            "item": "TGV",
            "quantity": 1200,
            "unit": "passager.km",
            "label": "Business trips by train"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("shadow-tools/ademe-emission-factors").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "electricité",
    "lines": [
        {
            "item": "électricité",
            "quantity": 5000,
            "unit": "kWh",
            "location": "France continentale",
            "label": "Office electricity",
        },
        {
            "item": "gazole",
            "quantity": 300,
            "unit": "litre",
            "label": "Company van fuel",
        },
        {
            "item": "TGV",
            "quantity": 1200,
            "unit": "passager.km",
            "label": "Business trips by train",
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("shadow-tools/ademe-emission-factors").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "electricité",
  "lines": [
    {
      "item": "électricité",
      "quantity": 5000,
      "unit": "kWh",
      "location": "France continentale",
      "label": "Office electricity"
    },
    {
      "item": "gazole",
      "quantity": 300,
      "unit": "litre",
      "label": "Company van fuel"
    },
    {
      "item": "TGV",
      "quantity": 1200,
      "unit": "passager.km",
      "label": "Business trips by train"
    }
  ]
}' |
apify call shadow-tools/ademe-emission-factors --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,shadow-tools/ademe-emission-factors"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/FgqQEEJWIyrjhn287/builds/6BCYOnWoTZ9hRshUI/openapi.json