# Car: BASIC

:bulb: **High-Level Description**

The **BASIC** methodology is a transparent, input-driven calculator for car travel when you already know either:

* the **specific emission rate** of the vehicle in **gCO₂/km**, **or**
* the **energy/fuel consumption** (e.g., L/100 km, kWh/100 km) **plus** the **fuel type** (to derive gCO₂/km via fuel-specific factors).

It is designed for simple, traceable calculations where the data source is your own measurement, OEM specs, or a trusted dataset. BASIC does **not** infer vehicle classes or default factors; it relies on **your supplied intensity** (g/km) or **your supplied consumption** with **explicit fuel type**.

**Audit mode:** Set `items[].audit = true` to create immutable audit records (must be enabled for your account).

***

## Sample API Requests

### A. Direct intensity (preferred when you know gCO₂/km)

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "car",
      "methodology": "BASIC",
      "external_reference": "TRIP-001",
      "distance_in_km": 245.6,
      "co2_grams_per_km": 120
    }
  ]
}
```

### B. Consumption-based (derive g/km from 100-km consumption + fuel type)

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "car",
      "methodology": "BASIC",
      "external_reference": "TRIP-002",
      "origin": "Munich, Germany",
      "destination": "Prague, Czechia",
      "consumption_per_100_km": 6.2,
      "fuel_type": "petrol"
    }
  ]
}
```

### C. With audit mode (for finalized/post-booking calculations)

```json
{
  "expand": ["items"],
  "audit_for": "<Auditable Entity ID>",
  "items": [
    {
      "audit": true,
      "type": "car",
      "methodology": "BASIC",
      "external_reference": "TRIP-004",
      "distance_in_km": 245.6,
      "co2_grams_per_km": 120
    }
  ]
}
```

### D. Duration-based distance fallback (when distance is unknown)

> If you don’t have distance or origin/destination, you may pass `number_of_days`.\
> SQUAKE estimates: `estimated_distance_in_km = number_of_days * 60`.

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "car",
      "methodology": "BASIC",
      "external_reference": "TRIP-003",
      "number_of_days": 4,
      "co2_grams_per_km": 95
    }
  ]
}
```

> **Precedence rules**\
> **Distance source:** `distance_in_km` > `origin/destination` > `number_of_days`.\
> **Intensity source:** `co2_grams_per_km` > (`consumption_per_100_km` + `fuel_type`).\
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.

***

## Sample API Response

```json
{
  "carbon_quantity": 29472,
  "carbon_unit": "gram",
  "items": [
    {
      "carbon_quantity": 29472,
      "carbon_unit": "gram",
      "external_reference": "TRIP-001",
      "type": "car",
      "methodology": "BASIC",
      "distance": 245.6,
      "distance_unit": "kilometer"
    }
  ]
}
```

***

## API Request Items

* `"type"`: `"car"` **(required)**
* `"methodology"`: `"BASIC"` **(required)**
* `"external_reference"`: Optional correlation ID (≤128 chars)
* **Distance inputs (choose one):**
  * `"distance_in_km"`: numeric (overrides other distance inputs)
  * `"origin"` **and** `"destination"`: postal text, UN/LOCODE, IATA/ICAO, or `"lat,lon"`
  * `"number_of_days"`: integer ≥ 1 (fallback; estimates distance as `days * 60`)
* **Intensity inputs (choose one path):**
  * `"co2_grams_per_km"`: number ≥ 0 **(direct gCO₂/km)**
  * **OR** `"consumption_per_100_km"` **and** `"fuel_type"`:
    * `"consumption_per_100_km"`: number \[0..1000]
    * `"fuel_type"`: one of\
      `"diesel" | "petrol" | "electricity" | "ethanol" | "bio_diesel" | "lpg" | "hydrogen" | "hvo"`
* `"audit"`: boolean (immutable audit record; feature-gated)

> **Validation tip:** For the **consumption** path, `fuel_type` is **mandatory**. For the **g/km** path, `fuel_type` is **not required**.

***

## Default Values

* No default for `"fuel_type"` (required **only** when using `"consumption_per_100_km"`).
* No default for `"co2_grams_per_km"` or `"consumption_per_100_km"`—you must provide **one** of the intensity paths.
* Distance estimation default for `"number_of_days"`: **60 km/day**.

***

## Notes

* Use **direct `co2_grams_per_km`** whenever available (OEM/telematics/lab data) for maximum fidelity.
* When using **consumption**, ensure the unit matches what your integration expects (e.g., **L/100 km** for liquid fuels, **kWh/100 km** for BEVs).
* BASIC does **not** infer vehicle classes or apply regional defaults; it uses exactly what you supply.
* For electric vehicles, either provide **`co2_grams_per_km`** (preferred if you have grid-mix allocation) or **`consumption_per_100_km`** with `"fuel_type": "electricity"` (uses configured electricity factors).

***

## Bibliography

* **Smart Freight Centre (SFC)** — *Global Logistics Emissions Council (GLEC) Framework for Logistics Emissions Accounting*, latest edition.
* **SFC** — *GLEC Framework Guidance & Technical Documentation* (supporting fuel/energy factors and calculation principles).