# CarbonSutra: The Carbon Emission API for Developers

CarbonSutra provides a comprehensive suite of APIs for calculating carbon footprints across various activities, including travel, logistics, energy, and fuel consumption. It is designed for seamless integration into enterprise systems, sustainability reports, and consumer applications.

## Documentation and Resources
- **Website:** [https://www.carbonsutra.com/](https://www.carbonsutra.com/)
- **API Reference:** Available via RapidAPI and the [CarbonSutra Product Pages](https://www.carbonsutra.com/data-vehicle-make-model.html).
- **Authentication:** Bearer Token (API Key) is required for clustering features. General testing is available via RapidAPI.

## Core Concepts
- **Emission Scopes:**
    - **Scope 1:** Direct emissions from owned or controlled sources (e.g., fuel combustion in company vehicles).
    - **Scope 2:** Indirect emissions from the generation of purchased energy (e.g., electricity).
    - **Scope 3:** All other indirect emissions in an organization's value chain (e.g., business travel, freight, eCommerce).
- **Clustering:** A unique feature allowing developers to group calculations with a `cluster_name`. This enables data retrieval and trend analysis without needing a local database.
- **Radiative Forcing (RF):** Accounts for the wider climate impact of high-altitude emissions.
- **Well-to-Tank (WTT):** Includes upstream emissions associated with extraction, refining, and transport of fuel.

---

## API Summary

### 1. Flights Travel
Calculates Scope 3 emissions based on airport-to-airport distance.
- **Endpoint:** `/flight_estimate`
- **Mandatory:** `iata_airport_from`, `iata_airport_to`, `number_of_passengers` (string).
- **Optional:** `flight_class` (Economy, Premium, Business, First), `round_trip` (Y/N), `add_rf` (Y/N), `include_wtt` (Y/N).
- **Data Source:** ICAO, EPA, IPCC.

### 2. Hotel Stay
Estimates carbon footprint based on country and star rating.
- **Endpoint:** `/hotel_estimate`
- **Mandatory:** `country_code` (ISO 3166-1 alpha-2), `number_of_rooms`, `number_of_nights`.
- **Optional:** `city_name`, `hotel_rating` (2, 3, 4, 5).
- **Data Source:** Cornell Hotel Sustainability Benchmark (CHSB).

### 3. Fuel Consumption
Computes Scope 1 emissions from stationary combustion fuels.
- **Endpoint:** `/fuel_estimate`
- **Mandatory:** `fuel_usage` (commercial, industrial, transport, residential), `fuel_name`, `fuel_value`.
- **Units:** Litres (Petrol, Diesel, Oils, Aviation), KG (Coal, LPG), kWh (Natural Gas).

### 4. Electricity Usage
Computes Scope 2 emissions for 90+ countries.
- **Endpoint:** `/electricity_estimate`
- **Mandatory:** `country_name`, `electricity_value`, `electricity_unit` (kWh, MWh).

### 5. Freight & Shipping
Covers Road, Rail, Air, and Sea (Short/Deep).
- **Endpoint:** `/freight_estimate`
- **Mandatory:** `transport_mode`, `freight_weight` (KG), `distance_value` (KM).

### 6. Vehicles (Type & Model)
Calculates emissions based on vehicle size or specific make/model.
- **Endpoints:** `/vehicle_estimate_by_type`, `/vehicle_estimate_by_model`.
- **Model Parameters:** `vehicle_make`, `vehicle_model`, `distance_value`, `distance_unit` (km, mi).

### 7. eCommerce Shipments
Advanced land-air-land journey algorithm using postal codes.
- **Endpoint:** `/ecommerce_estimate`
- **Mandatory:** `origin_country_code`, `origin_postal_code`, `destination_country_code`, `destination_postal_code`, `package_weight` (KG).

---

## MCP Server Implementation Guidance
When building an MCP server for CarbonSutra, follow these rules:
1. **Parameter Validation:** Ensure `number_of_passengers` and similar numeric values are passed as strings if required by the endpoint.
2. **Unit Conversion:** Always clarify if the input distance is in KM or MI. Default to KM for consistency where applicable.
3. **Clustering:** Implement a method to set a global `cluster_name` and `Authorization` header for session-wide tracking.
4. **Helper Tools:** Provide tools to search for IATA codes (`/airports-by-keyword`) and vehicle models (`/vehicle_makes/{make}/vehicle_models`) to prevent user input errors.
5. **Output Parsing:** CarbonSutra returns CO2e in multiple units (gm, kg, mt, lb). The MCP tool should return all units to provide maximum context to the LLM.

## Use Cases
- **Sustainability Dashboards:** Use Clustering to track monthly CO2e across departments.
- **Checkout Integration:** Calculate shipping emissions in real-time for eCommerce.
- **Business Travel Policy:** Automate Scope 3 reporting for employee flights.