# Real-World vs Official Fuel Consumption Data (`fetchfinch/real-world-fuel-consumption`) Actor

Compare real-world fuel consumption with manufacturer-declared NEDC/WLTP figures across 9,894 vehicle variants. Coverage is strongest for European and UK-market specifications and is not intended for US- or Canadian-market-specific lookup.

- **URL**: https://apify.com/fetchfinch/real-world-fuel-consumption.md
- **Developed by:** [Fetch Finch](https://apify.com/fetchfinch) (community)
- **Categories:** Developer tools, E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 vehicle consumption 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/platform/actors/running/actors-in-store#pay-per-event

## 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

## Real-World vs Official Fuel Consumption Data

Discover how much fuel vehicles actually use, not just what manufacturers claim. Compare and export real-world consumption against official NEDC/WLTP figures across 9,894 vehicle variants.

The dataset contains thousands of combustion and hybrid engine variants with manufacturer-declared values, real-world MPG where available, normalized l/100km conversions, and the calculated percentage gap between official and real-world consumption.

### What this Actor is useful for

- Automotive marketplaces and comparison tools
- Fuel-cost and total-cost-of-ownership calculators
- Fleet analysis and procurement tooling
- Automotive journalism and research
- Enriching internal vehicle datasets with real-world consumption estimates

### Coverage

Current dataset snapshot:

- 54 vehicle brands
- 1,012 model generations
- 9,894 engine variants
- 7,222 variants with real-world MPG
- 8,414 variants with NEDC values
- 2,652 variants with WLTP values

Coverage is strongest for European and UK-market petrol, diesel, hybrid, mild-hybrid, and plug-in hybrid specifications, many of which are also relevant in Latin America, Asia, Africa, and Oceania. It is not intended as a US- or Canadian-market-specific fuel-economy database, VIN decoder, EV consumption API, or complete new-car database.

### Input

The Actor supports five operations:

- `search` - free-text search, e.g. `volkswagen golf 1.4 tsi 150 dsg`
- `lookup` - filter by brand/model/engine/fuel/year
- `brand` - export records for one brand
- `export` - filtered dataset export
- `stats` - summary statistics

Example input:

```json
{
  "operation": "search",
  "searchQuery": "volkswagen golf 1.4 tsi 150 dsg",
  "hasRealConsumptionOnly": true,
  "officialStandard": "prefer-wltp",
  "outputUnits": "both",
  "maxResults": 25
}
```

Brand export example:

```json
{
  "operation": "brand",
  "brandName": "Volkswagen",
  "hasRealConsumptionOnly": true,
  "maxResults": 1000
}
```

Filtered export example:

```json
{
  "operation": "export",
  "fuelTypes": ["diesel"],
  "yearFrom": 2015,
  "yearTo": 2020,
  "minDeviationPct": 20,
  "sortBy": "deviation",
  "sortOrder": "desc",
  "maxResults": 500
}
```

### Output

Each dataset item represents one engine variant:

```json
{
  "recordType": "vehicle-consumption",
  "brand": "Volkswagen",
  "brandSlug": "volkswagen",
  "model": "Golf",
  "modelYears": "2012 - 2020",
  "engine": "1.4 TSI 150 DSG",
  "fuelType": "petrol",
  "selectedOfficialStandard": "NEDC",
  "officialMpgNedc": 59.5,
  "officialMpgWltp": null,
  "selectedOfficialMpg": 59.5,
  "realMpgAvg": 44.2,
  "officialConsumptionL100km": 4.75,
  "realConsumptionL100km": 6.39,
  "realVsOfficialConsumptionDeviationPct": 34.5,
  "dataQuality": {
    "hasRealConsumption": true,
    "hasWltp": false,
    "hasNedc": true,
    "hasDisplacement": true,
    "flags": ["missing-wltp"]
  }
}
```

The key-value store entry `OUTPUT` contains a run summary with total matched and returned records.

### Important interpretation notes

- MPG values are UK MPG.
- l/100km is derived with `282.481 / UK MPG`.
- `selectedOfficialStandard` identifies whether the derived official l/100km value used WLTP or NEDC.
- `realVsOfficialConsumptionDeviationPct` is based on l/100km, so positive means real-world consumption is worse than the official figure.
- Source percentage fields are preserved as `realVsOfficialMpgPct` when MPG output is enabled. That value is MPG-based and therefore has the opposite intuition: lower percentages mean worse real-world fuel economy.
- Plug-in hybrid records can have very high official MPG due to test-cycle behavior. Use quality flags when comparing PHEVs with conventional vehicles.

### Recommended monetization

Use Apify pay-per-event pricing on default dataset items. The Actor is CPU-light and deterministic, so per-result pricing is predictable for users.

Suggested initial pricing:

- Small per-run/start charge, if desired
- Approximately `$2–$3 per 1,000 returned records`
- Include platform usage in the price for simpler buyer expectations

### Limitations

- Mostly European and UK-market coverage.
- Sparse EV and hydrogen coverage.
- Sparse US- and Canadian-market-specific coverage.
- Not a VIN decoder.
- Not a substitute for official regulatory databases.
- Real-world consumption varies by driving style, condition, weather, tires, load, and terrain.

# Actor input Schema

## `operation` (type: `string`):

Choose whether to search, filter/export records, return one brand, or produce summary statistics.

## `searchQuery` (type: `string`):

Free-text query such as 'volkswagen golf 1.4 tsi 150 dsg', 'toyota corolla hybrid', or 'bmw 320d'. Used by the Search operation.

## `brandName` (type: `string`):

Select or type a vehicle brand. Required for Brand export and optional for Lookup or Filtered export.

## `modelName` (type: `string`):

Optional model-name filter, e.g. Golf, Corolla, or Giulia. Type a model belonging to the selected brand.

## `engine` (type: `string`):

Optional engine filter, e.g. 1.6 TDI, 320d, 1.0 TSI.

## `fuelTypes` (type: `array`):

Optional normalized fuel-type filters. Leave empty to include all fuel types.

## `yearFrom` (type: `integer`):

Optional lower bound for model-generation overlap. Example: 2015.

## `yearTo` (type: `integer`):

Optional upper bound for model-generation overlap. Example: 2020.

## `hasRealConsumptionOnly` (type: `boolean`):

If enabled, excludes variants where real-world MPG is missing.

## `officialStandard` (type: `string`):

Controls which official value is used for the derived officialConsumptionL100km and deviation fields.

## `minDeviationPct` (type: `integer`):

Optional lower bound for real vs official l/100km deviation. Example: 20 returns cars at least 20% worse than official.

## `outputUnits` (type: `string`):

Choose consumption units in output. Raw source strings can also be included separately.

## `sortBy` (type: `string`):

Sort result records. Relevance is meaningful for search operation.

## `sortOrder` (type: `string`):

Ascending or descending sort order.

## `includeRaw` (type: `boolean`):

Include original MPG and percentage strings from the dataset for auditability.

## `includeQualityFlags` (type: `boolean`):

Include availability and sanity flags for each record.

## `offset` (type: `integer`):

Number of matched records to skip. Useful for pagination.

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

Maximum number of result records to write to the dataset. Full dataset is under 10,000 records.

## Actor input object example

```json
{
  "operation": "search",
  "searchQuery": "volkswagen golf 1.4 tsi 150 dsg",
  "fuelTypes": [],
  "hasRealConsumptionOnly": true,
  "officialStandard": "prefer-wltp",
  "outputUnits": "both",
  "sortBy": "relevance",
  "sortOrder": "asc",
  "includeRaw": false,
  "includeQualityFlags": true,
  "offset": 0,
  "maxResults": 100
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset containing matched vehicle engine variants or dataset statistics.

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

Summary containing record counts, applied filters, pagination, and coverage 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 = {
    "searchQuery": "volkswagen golf 1.4 tsi 150 dsg"
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetchfinch/real-world-fuel-consumption").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 = { "searchQuery": "volkswagen golf 1.4 tsi 150 dsg" }

# Run the Actor and wait for it to finish
run = client.actor("fetchfinch/real-world-fuel-consumption").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 '{
  "searchQuery": "volkswagen golf 1.4 tsi 150 dsg"
}' |
apify call fetchfinch/real-world-fuel-consumption --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetchfinch/real-world-fuel-consumption"
        }
    }
}

```

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/tqEStipkLo61Oh2p6/builds/dp5OeFlSXpnR3NMPO/openapi.json