> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Emission Groups

> Organize and manage custom emission factors into groups

# Custom Emission Groups

Custom Emission Groups are containers that organize related custom emission factors by category. They provide structure and context for your organization's custom emission data.

## Overview

### What are Custom Emission Groups?

Custom Emission Groups act as folders or categories for organizing custom emission factors. Each group:

* Contains multiple related custom emission factors
* Has a specific category (purchases, wastes, or energy)
* Defines the GHG type (fossil, biogenic, or mixed)
* Belongs to a single organization

### Hierarchy

```
Organization
└── Custom Emission Group (category: purchases)
    ├── Custom Emission Factor 1
    ├── Custom Emission Factor 2
    └── Custom Emission Factor 3
```

## Categories

Custom Emission Groups are organized by three categories:

### Purchases (`purchases`)

Groups for supplier-specific product emission factors.

**Example:** "Supplier ABC Materials 2024"

* Recycled aluminum sheets
* Steel beams
* Plastic components

### Wastes (`wastes`)

Groups for custom waste treatment emission factors.

**Example:** "Local Waste Facility Factors"

* Incineration with energy recovery
* Recycling processes
* Landfill disposal

### Energy (`energy`)

Groups for renewable energy contracts and custom energy factors.

**Example:** "Wind Farm PPA 2024-2034"

* 100% renewable wind energy
* Solar PPA contracts
* On-site generation

## GHG Types

Each group specifies the GHG origin type:

| Type         | Value | Description                        | Example                                 |
| ------------ | ----- | ---------------------------------- | --------------------------------------- |
| **Fossil**   | `1`   | Fossil fuel-derived emissions      | Conventional energy, petroleum products |
| **Biogenic** | `2`   | Biological origin emissions        | Biomass, biogas, biofuels               |
| **Mixed**    | `3`   | Combination of fossil and biogenic | Mixed waste streams, hybrid processes   |

## Workflow

<Steps>
  <Step title="Create Custom Emission Group">
    Define a group to organize your custom factors

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    POST /api/v1/custom_emission_groups
    ```
  </Step>

  <Step title="Add Custom Emission Factors">
    Add individual factors to the group

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    POST /api/v1/custom_emission_factors/{group_id}
    ```
  </Step>

  <Step title="Use in Operations">
    Reference factors when creating purchases, wastes, or energy records

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "custom_emission_factor_id": "factor-uuid",
      ...
    }
    ```
  </Step>

  <Step title="Manage and Update">
    Update group metadata or factors as needed

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    PATCH /api/v1/custom_emission_groups/{id}
    PATCH /api/v1/custom_emission_factors/{id}
    ```
  </Step>
</Steps>

## Data Structure

### Custom Emission Group

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "group-uuid",
  "name": "Supplier ABC Products 2024",
  "description": "Custom emission factors from Supplier ABC with EPD verification",
  "category": "purchases",
  "ghg_type": 1,
  "organization_id": "org-uuid"
}
```

### Key Fields

<ParamField body="name" type="string" required>
  Descriptive name for the group

  **Example:** `"Supplier XYZ Materials 2024"`
</ParamField>

<ParamField body="description" type="string">
  Detailed description of the group's purpose

  **Example:** `"EPD-verified emission factors for all materials from Supplier XYZ, valid for 2024"`
</ParamField>

<ParamField body="category" type="string" required>
  Category type

  **Values:** `"purchases"`, `"wastes"`, or `"energy"`
</ParamField>

<ParamField body="ghg_type" type="integer" required>
  GHG origin type

  **Values:** `1` (fossil), `2` (biogenic), or `3` (mixed)
</ParamField>

## API Endpoints

<CardGroup cols={2}>
  <Card title="Create Group" icon="folder-plus" href="/api-docs/custom-emission-groups/create">
    Create new emission group
  </Card>

  <Card title="List Groups" icon="list" href="/api-docs/custom-emission-groups/list">
    View all groups
  </Card>

  <Card title="Get Group" icon="magnifying-glass" href="/api-docs/custom-emission-groups/get">
    Retrieve group details
  </Card>

  <Card title="Update Group" icon="pen" href="/api-docs/custom-emission-groups/update">
    Modify group metadata
  </Card>

  <Card title="Delete Group" icon="trash" href="/api-docs/custom-emission-groups/delete">
    Remove group
  </Card>

  <Card title="Get Units" icon="ruler" href="/api-docs/custom-emission-groups/units">
    List available units
  </Card>

  <Card title="List by Category" icon="filter" href="/api-docs/custom-emission-groups/list-by-category">
    Filter groups by category
  </Card>

  <Card title="Organization Data" icon="building" href="/api-docs/custom-emission-groups/organization-data">
    Get all organization groups
  </Card>
</CardGroup>

## Best Practices

### 1. Organize by Source

Create groups based on data source:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Supplier-specific group
{
    "name": "Supplier ABC - 2024 EPD Data",
    "description": "All materials from Supplier ABC with third-party verified EPDs",
    "category": "purchases",
    "ghg_type": 1
}

# Facility-specific group
{
    "name": "Local Waste Facility - 2024",
    "description": "Custom waste treatment factors for our regional waste facility",
    "category": "wastes",
    "ghg_type": 3
}
```

### 2. Use Clear Naming Conventions

Include year, source, and scope in names:

```
✅ Good names:
- "Supplier XYZ Materials 2024"
- "Wind Farm PPA 2024-2034"
- "Local Recycling Center Q1-Q2 2024"

❌ Unclear names:
- "Custom Factors"
- "Group 1"
- "Materials"
```

### 3. Document Everything

Use the description field extensively:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "name": "Renewable Energy PPA Portfolio",
    "description": """
        Combined renewable energy factors from multiple PPAs:
        - Wind Farm A (60% allocation, 100MW capacity)
        - Solar Farm B (40% allocation, 50MW capacity)
        Contract period: 2024-01-01 to 2034-12-31
        Third-party verification: Bureau Veritas, Report #2024-001
        Contact: energy_procurement@company.com
    """,
    "category": "energy",
    "ghg_type": 2
}
```

### 4. One Group per Category per Source

Don't mix categories or sources:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# ✅ Good: One category, one source
{
    "name": "Supplier ABC Purchases 2024",
    "category": "purchases",
    "ghg_type": 1
}

# ❌ Bad: Mixing multiple sources or categories
# Create separate groups instead
```

## Common Use Cases

### Supplier Product Portfolio

Organize all products from a single supplier:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "GreenTech Materials 2024",
  "description": "EPD-verified factors for all GreenTech products, updated quarterly",
  "category": "purchases",
  "ghg_type": 1
}
```

Then add factors:

* Recycled aluminum sheets
* Steel beams (low-carbon)
* Composite materials
* Packaging materials

### Regional Waste Management

Group factors for a specific waste facility:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "Regional Waste Facility - 2024",
  "description": "Custom factors for local waste treatment facility with energy recovery",
  "category": "wastes",
  "ghg_type": 3
}
```

Factors:

* Incineration with energy recovery
* Composting (organic waste)
* Recycling (paper, plastic, metal)
* Landfill disposal

### Renewable Energy Portfolio

Organize PPA contracts:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "Renewable Energy Portfolio 2024-2034",
  "description": "10-year PPAs for wind and solar energy, 100% renewable allocation",
  "category": "energy",
  "ghg_type": 2
}
```

Factors:

* Wind farm PPA (60% allocation)
* Solar farm PPA (40% allocation)
* On-site solar panels

## Validation Requirements

### Required Fields

* ✅ Name (`name`)
* ✅ Category (`category`) - must be `purchases`, `wastes`, or `energy`
* ✅ GHG type (`ghg_type`) - must be `1`, `2`, or `3`

### Optional but Recommended

* 📝 Description (`description`) - provide context and documentation

### Automatic Checks

* ⚠️ Category must be valid (`purchases`, `wastes`, or `energy`)
* ⚠️ GHG type must be 1, 2, or 3
* ⚠️ Name must be unique within organization (recommended)

## Related Documentation

<CardGroup cols={2}>
  <Card title="Custom Emission Factors" icon="chart-line" href="/api-docs/custom-emission-factors/overview">
    Add factors to groups
  </Card>

  <Card title="Purchases" icon="shopping-cart" href="/api-docs/purchases/list">
    Use custom factors in purchases
  </Card>

  <Card title="Wastes" icon="trash" href="/api-docs/wastes/codes">
    Apply to waste management
  </Card>

  <Card title="Units" icon="ruler" href="/api-docs/units/list">
    Available measurement units
  </Card>
</CardGroup>