# Carbon Monitor Scraper (`codingfrontend/carbon-monitor-scraper`) Actor

Extract daily country- and sector-level CO2 estimates from Carbon Monitor public data; independent and not endorsed by Carbon Monitor.

- **URL**: https://apify.com/codingfrontend/carbon-monitor-scraper.md
- **Developed by:** [Coding Frontned](https://apify.com/codingfrontend) (community)
- **Categories:** Other, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does Carbon Monitor Scraper do?

Carbon Monitor Scraper downloads the public Carbon Monitor global daily emissions CSV and returns normalized country- or region-level records by date and sector. It is a lightweight **Carbon Monitor API alternative** for scheduled data collection, analysis, dashboards, spreadsheets, and data warehouses, using the public [Carbon Monitor](https://carbonmonitor.org/) source.

This is an independent community integration. It is not affiliated with or endorsed by Carbon Monitor or its supporting institutions, and it does not access private accounts or protected data.

### Why use Carbon Monitor Scraper?

Use the Actor when you need repeatable daily estimates of fossil-fuel and cement-production CO2 emissions in a machine-readable dataset. It provides:

- exact, case-insensitive country or region filtering;
- sector filtering for Domestic Aviation, Ground Transport, Industry, International Aviation, Power, and Residential;
- inclusive ISO date-range filtering;
- stable country-date-sector record IDs and duplicate suppression;
- source URL, source page, release filename, release date, unit, and extraction timestamp;
- bounded retries, response-size, scan-count, and run-time guards; and
- explicit diagnostic rows when no usable result is available, without counting diagnostics as successful records.

Because the Actor runs on Apify, you can schedule it, access it through the API, connect it to integrations, monitor runs, and optionally provide Apify Proxy settings through the input tab. Direct access is the normal configuration.

### What data can Carbon Monitor Scraper extract?

| Field | Type | Description |
| --- | --- | --- |
| `recordId` | string | Lowercase country-date-sector identity. |
| `country` | string | Country or region as published by Carbon Monitor. |
| `date` | string | Daily estimate date in `YYYY-MM-DD` format. |
| `sector` | string | Carbon Monitor sector. |
| `emissionsMtCO2PerDay` | number | Estimated emissions in million tonnes of CO2 per day. |
| `unit` | string | Always `MtCO2/day` for successful records. |
| `sourceDatasetReleaseDate` | string | Release date parsed from the download filename when present. |
| `sourceFileName` | string | Filename supplied by the public download response when present. |
| `source`, `sourceDomain`, `pageType`, `extractionMethod` | string | Explicit public-source provenance and record classification. |
| `sourceUrl` / `sourcePageUrl` | string | Exact public CSV endpoint and Carbon Monitor landing page. |
| `found` / `dataAvailable` | boolean | Result status flags; diagnostic rows set both to `false`. |
| `diagnosticType` / `diagnosticMessage` | string | Present on explicit diagnostic rows. |

### How to scrape Carbon Monitor

1. Open the **Input** tab and choose a country or region, sector, optional inclusive date range, and result cap.
2. Keep the default direct-access configuration unless your operating environment requires the optional proxy setting.
3. Click **Start**. The Actor fetches the public CSV, validates the response and content type, and normalizes matching rows.
4. Open the **Dataset** tab or use the **API** tab to download the results.

The source file currently uses a `country,date,sector,value` CSV layout with dates such as `01/01/2019`; the Actor converts those dates to ISO form. The Actor reads the HTTP response into a buffer, rejects it when its size exceeds `maxDownloadMbytes`, and then feeds the accepted buffer to the CSV parser. `maxRowsScanned` and `maxRunMillis` prevent an unexpectedly large or slow source from running indefinitely.

### How much will it cost to scrape Carbon Monitor?

This Actor does not add a per-result charge or implement pay-per-event billing. Your total cost is the normal Apify compute and storage usage for your plan; the exact amount depends on the response size, filters, and how often you schedule runs. Narrow country, sector, and date filters reduce dataset volume, while the size, scan, retry, and run-time limits keep resource use predictable.

### Input

See the **Input** tab for full configuration options. A focused request can look like this:

```json
{
  "country": "Austria",
  "sector": "Power",
  "dateFrom": "2019-01-01",
  "dateTo": "2019-01-31",
  "maxResults": 100
}
```

`country` is an exact case-insensitive match. Leave it empty to include all published countries and regions. `sector` accepts `all` or one of the six published sectors. `dateFrom` and `dateTo` are optional inclusive ISO dates. `maxResults`, `maxRowsScanned`, `maxDownloadMbytes`, `maxRunMillis`, and `maxRetries` are bounded by the input schema. The optional `proxyConfiguration` is retained for compatible Apify deployments but is disabled by default.

### Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. A successful record has this shape:

```json
{
  "recordId": "exampleland|2025-01-15|power",
  "country": "Exampleland",
  "date": "2025-01-15",
  "sector": "Power",
  "emissionsMtCO2PerDay": 0.123456,
  "unit": "MtCO2/day",
  "isDiagnostic": false,
  "found": true,
  "dataAvailable": true,
  "sourceDatasetReleaseDate": "2026-01-15",
  "sourceFileName": "carbonmonitor-global_datas_2026-01-15.csv",
  "sourceUrl": "https://datas.carbonmonitor.org/API/downloadFullDataset.php?source=carbon_global",
  "sourcePageUrl": "https://carbonmonitor.org/",
  "source": "Carbon Monitor global daily CSV",
  "sourceDomain": "datas.carbonmonitor.org",
  "pageType": "emissions_observation",
  "extractionMethod": "public_csv",
  "scrapedAt": "2026-01-15T12:00:00.000Z"
}
```

If no matching result is available or the request cannot produce usable data, the Actor emits one explicit diagnostic row instead of a fabricated record. It contains `isDiagnostic: true`, `found: false`, and `dataAvailable: false`, plus `diagnosticType` and `diagnosticMessage`. Diagnostic rows are excluded from the Actor's reported successful-record count.

No-data and source-failure runs deliberately finish with a non-success status after saving that diagnostic evidence. This prevents an empty or diagnostic-only extraction from being mistaken for a successful data delivery.

### Tips / Advanced options

- Set `maxResults` low for a quick smoke of a narrow filter and raise it for historical extracts.
- Keep `maxRowsScanned` high enough for the selected country/date range; reaching the cap before a match produces a diagnostic row.
- Raise `maxDownloadMbytes` only when the public CSV has grown beyond the configured guard.
- Keep `maxRunMillis` below five minutes and use `maxRetries` between one and three.
- Treat the values as scientific estimates that may be revised when Carbon Monitor updates its methods or source data.

### Key-value store

Every run writes `OUTPUT_SUMMARY` to the default key-value store. It reports the completion status, successful and diagnostic counts, rows scanned, whether a proxy was requested, source release metadata when available, and the completion timestamp. The dataset remains the authoritative home for observations and diagnostic rows.

### Validation and reliability

Successful observations can be checked with `npm run validate` after a local run. The validator requires at least one real observation, verifies 100% completion of the required fields, canonical country-date-sector IDs, unique records, finite non-negative emissions, exact units and source URLs, strict dates and timestamps, and correlated source release metadata. `npm test` covers strict input parsing, calendar edge cases, proxy validation, filename parsing, challenge detection, and diagnostic provenance.

### FAQ, disclaimers, and support

#### Are these official national emissions inventories?

No. The output contains estimates from Carbon Monitor's public dataset. Coverage, sector definitions, and revisions follow the source; users remain responsible for interpreting and citing the underlying research.

#### What happens when the source is unavailable?

The Actor stops retrying when it encounters an access-denial or challenge response and records a sanitized diagnostic row. It does not bypass CAPTCHA, login, paywall, geofence, WAF, or rate-limit controls, and it does not substitute a private or mirrored endpoint.

#### Does this Actor collect personal data?

Our Actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our Actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

For programmatic use, see the **API** tab. For feedback, unexpected source changes, or troubleshooting, use the **Issues** tab and include the input filters and diagnostic row without sharing credentials.

# Actor input Schema

## `country` (type: `string`):

Optional case-insensitive exact country/region name. Leave empty to include all.

## `sector` (type: `string`):

Optional exact Carbon Monitor sector.

## `dateFrom` (type: `string`):

Optional inclusive ISO date (YYYY-MM-DD).

## `dateTo` (type: `string`):

Optional inclusive ISO date (YYYY-MM-DD).

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

Maximum unique daily country-sector records to save.

## `maxRowsScanned` (type: `integer`):

Safety cap while streaming the downloaded CSV.

## `maxDownloadMbytes` (type: `integer`):

Reject the buffered public CSV response if it exceeds this configured size guard.

## `maxRunMillis` (type: `integer`):

Actor-side deadline capped below five minutes.

## `maxRetries` (type: `integer`):

Bounded attempts with exponential backoff.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy. The public Carbon Monitor endpoint normally works directly.

## Actor input object example

```json
{
  "country": "Austria",
  "sector": "all",
  "maxResults": 100,
  "maxRowsScanned": 2000000,
  "maxDownloadMbytes": 100,
  "maxRunMillis": 240000,
  "maxRetries": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Dataset containing normalized Carbon Monitor records and explicit diagnostic rows for non-success outcomes.

## `summary` (type: `string`):

Run status, record counts, source metadata, and route information.

# 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 = {
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("codingfrontend/carbon-monitor-scraper").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 = { "proxyConfiguration": { "useApifyProxy": False } }

# Run the Actor and wait for it to finish
run = client.actor("codingfrontend/carbon-monitor-scraper").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 '{
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call codingfrontend/carbon-monitor-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,codingfrontend/carbon-monitor-scraper"
        }
    }
}

```

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/f1HvV9II0gv2Ly659/builds/zCJvuUBlUukpofHR1/openapi.json