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

# Step 2: Configure Hubs & Track Hub Emissions

> Set up logistics hubs, assign HOC categories, and track hub-level emissions following GLEC v3.0

## Understanding Hub Operations in GLEC

In the GLEC Framework, **hub operations** cover emissions from logistics facilities — warehouses, cross-docking centers, distribution hubs, and cold storage facilities. These emissions are separate from transport and include energy consumption (electricity, heating) and operational processes.

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                          HUB OPERATIONS IN GLEC                              │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Owned Hubs (Scope 1 + 2)              Subcontracted Hubs (Scope 3)        │
│  ──────────────────────                ─────────────────────────            │
│  • Linked to a Facility                • Uses HOC default intensity        │
│  • Scope 1: On-site fuel               • All emissions → Scope 3          │
│    combustion (heating, forklifts)      • HOC intensity: kgCO2e/tonne     │
│  • Scope 2: Purchased electricity       • Multiplied by tonnes handled    │
│  • Real energy data from invoices                                          │
│                                                                              │
│  Hub Operation IV = Hub emissions (gCO2e) / Tonnes handled                 │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
```

<Note>
  **Hub Emission Sources**

  For **owned hubs**, Dcycle uses actual energy data from linked facilities:

  * **Scope 1**: Direct fuel combustion (natural gas, diesel generators)
  * **Scope 2**: Purchased electricity and district heating

  For **subcontracted hubs**, Dcycle uses **HOC default intensity values** (kgCO2e/tonne) based on the hub category.

  **Hub CO2e = HOC intensity (kgCO2e/tonne) x Tonnes handled**
</Note>

## Prerequisites

Before starting, ensure you have:

* Dcycle API credentials ([get them here](/docs/quickstart#step-1-get-your-api-key))
* Your organization set up in Dcycle
* Hub details: name, address, type (owned/subcontracted), and category
* For owned hubs: a Facility already created in Dcycle (with energy invoices for actual emissions)

## HOC Categories

Each hub is assigned a **HOC (Hub Operation Category)** that determines its default emission intensity:

| Category                               | Description                        | Typical IV (kgCO2e/tonne) |
| -------------------------------------- | ---------------------------------- | ------------------------- |
| `transshipment_ambient`                | Ambient temp cross-docking/sorting | Low                       |
| `transshipment_mixed`                  | Mixed temp handling                | Medium                    |
| `transshipment_temperature_controlled` | Refrigerated/frozen handling       | High                      |
| `cold_storage`                         | Cold/frozen warehousing            | Highest                   |
| `warehouse_ambient`                    | Ambient warehousing                | Low                       |

<Tip>
  Choose the category that best matches your hub's primary operation. Temperature-controlled facilities have significantly higher emission intensities due to refrigeration energy.
</Tip>

## Step 2.1: Create a Hub

<Accordion title="📋 Data Map: Create Hub">
  | Field          | Type    | Required    | Description                                            | Example                        |
  | -------------- | ------- | ----------- | ------------------------------------------------------ | ------------------------------ |
  | `name`         | string  | Yes         | Unique hub name within your organization               | `"Madrid Distribution Center"` |
  | `address`      | string  | Yes         | Physical address (geocoded for country resolution)     | `"Calle Logistica 1, Madrid"`  |
  | `type`         | string  | Yes         | `"owned"` or `"subcontracted"`                         | `"owned"`                      |
  | `category`     | string  | Yes         | HOC category                                           | `"transshipment_ambient"`      |
  | `facility_id`  | string  | Conditional | Required for `owned` hubs — links to a Dcycle Facility | `"fac-uuid-123"`               |
  | `supercharger` | boolean | Yes         | Has electric vehicle charging infrastructure           | `false`                        |

  **Where to get this data:**

  * **facility\_id**: From your Dcycle Facilities list (created via Facilities API or web app)
  * **category**: Match to the HOC categories above based on your hub's operations
  * **address**: Physical address of the hub (validated via geocoding)
</Accordion>

### Create an owned hub (linked to a Facility)

Owned hubs use real energy data from a linked Facility for Scope 1/2 emissions:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  headers = {
      "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
      "Content-Type": "application/json",
      "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
      "x-partner": os.getenv("DCYCLE_PARTNER_ID"),
  }

  # Create an owned logistics hub linked to an existing facility
  hub = {
      "name": "Madrid Distribution Center",
      "address": "Polígono Industrial San Fernando, Calle 3, Madrid, Spain",
      "type": "owned",
      "category": "transshipment_ambient",
      "facility_id": "your-facility-uuid",  # From Facilities API
      "supercharger": True,
  }

  response = requests.post(
      "https://api.dcycle.io/logistic_hubs",
      headers=headers,
      json=hub,
  ).json()

  print(f"Hub created: {response['id']}")
  print(f"Name: {response['name']}")
  print(f"Type: {response['type']}")
  print(f"Category: {response['category']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const headers = {
    Authorization: `Bearer ${process.env.DCYCLE_API_KEY}`,
    'Content-Type': 'application/json',
    'x-organization-id': process.env.DCYCLE_ORG_ID,
    'x-partner': process.env.DCYCLE_PARTNER_ID,
  };

  // Create an owned logistics hub linked to an existing facility
  const hub = {
    name: 'Madrid Distribution Center',
    address: 'Polígono Industrial San Fernando, Calle 3, Madrid, Spain',
    type: 'owned',
    category: 'transshipment_ambient',
    facility_id: 'your-facility-uuid',
    supercharger: true,
  };

  const { data: result } = await axios.post(
    'https://api.dcycle.io/logistic_hubs',
    hub,
    { headers }
  );

  console.log(`Hub created: ${result.id}`);
  console.log(`Name: ${result.name}`);
  console.log(`Type: ${result.type}`);
  console.log(`Category: ${result.category}`);
  ```
</CodeGroup>

### Create a subcontracted hub

Subcontracted hubs use HOC default intensity values — no facility link needed:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Create a subcontracted hub
hub = {
    "name": "Barcelona 3PL Warehouse",
    "address": "Zona Franca, Barcelona, Spain",
    "type": "subcontracted",
    "category": "transshipment_mixed",
    "supercharger": False,
}

response = requests.post(
    "https://api.dcycle.io/logistic_hubs",
    headers=headers,
    json=hub,
).json()

print(f"Hub created: {response['id']}")
```

<Warning>
  **Owned hubs require a `facility_id`**

  When creating an owned hub, you must provide a valid `facility_id` pointing to an existing Dcycle Facility. The Facility is where you upload energy invoices (electricity, gas, etc.) that provide actual Scope 1 and Scope 2 emission data for the hub.

  Create a Facility first via the [Facilities API](/api-reference/facilities) or the Dcycle web app.
</Warning>

## Step 2.2: List and Manage Hubs

### List all hubs

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Get paginated list of hubs
response = requests.get(
    "https://api.dcycle.io/logistic_hubs",
    headers=headers,
    params={"page": 1, "size": 50},
).json()

print(f"Total hubs: {response['total']}")
for hub in response["items"]:
    co2e_display = f"{hub['co2e']:.2f} kg" if hub.get("co2e") else "N/A"
    print(f"  {hub['name']:35s} | {hub['type']:15s} | {hub['category']:30s} | CO2e: {co2e_display}")
```

### Update a hub

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Update hub category or address
hub_id = "your-hub-uuid"

update = {
    "category": "transshipment_temperature_controlled",
    "address": "New Address, Madrid, Spain",
}

response = requests.patch(
    f"https://api.dcycle.io/logistic_hubs/{hub_id}",
    headers=headers,
    json=update,
).json()

print(f"Hub updated: {response['name']}")
print(f"New category: {response['category']}")
```

<Note>
  **Automatic recalculation**: When you update a hub's address, Dcycle automatically triggers a recalculation of all transport legs associated with that hub to update distances and emissions.
</Note>

### Delete a hub

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
hub_id = "your-hub-uuid"

response = requests.delete(
    f"https://api.dcycle.io/logistic_hubs/{hub_id}",
    headers=headers,
)

if response.status_code == 200:
    print("Hub deleted successfully")
elif response.status_code == 409:
    print("Cannot delete: hub is referenced by transport legs or has invoices")
```

<Warning>
  **Deletion constraints**: A hub cannot be deleted if it is referenced by any transport legs (`hub_id` in logistics requests) or if its linked facility has invoices. Remove references first, or archive the hub by updating its status instead.
</Warning>

## Step 2.3: Link Hubs to Transport Legs

When creating transport legs ([Step 1](/guides/emissions/glec-step-1-transport-operations)), associate them with a hub using the `hub_id` field:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Transport leg associated with a hub
shipment = {
    "origin": "Madrid Distribution Center",
    "destination": "Barcelona, Spain",
    "toc": "artic_truck_diesel",
    "load": 15,
    "load_unit": "ton",
    "hub_id": "HUB-MAD-001",  # Hub name or ID
    "client": "RETAILCO",
}

response = requests.post(
    "https://api.dcycle.io/v1/logistics/requests",
    headers=headers,
    json=shipment,
).json()
```

This links the transport leg to the hub, allowing the GLEC report to aggregate transport activity by hub and include hub-level emissions in the company report.

## How Hub Emissions Appear in the GLEC Report

Hub emissions are allocated across scopes in the [GLEC Company Report](/guides/emissions/glec-step-4-reports):

| Hub Type          | Scope 1                                          | Scope 2                                        | Scope 3                         |
| ----------------- | ------------------------------------------------ | ---------------------------------------------- | ------------------------------- |
| **Owned**         | On-site fuel combustion (from Facility invoices) | Purchased electricity (from Facility invoices) | —                               |
| **Subcontracted** | —                                                | —                                              | HOC default IV x tonnes handled |

The report also calculates the **Hub Operation Intensity Value**:

**Hub Operation IV = Total hub emissions (gCO2e) / Total tonnes handled**

<Tip>
  **Best Practice: Improve hub accuracy over time**

  1. Start with **subcontracted** hubs using HOC defaults for a quick baseline
  2. For significant hubs, switch to **owned** and link a Facility
  3. Upload energy invoices to the Facility for actual Scope 1/2 data
  4. This progression moves you from default factors to measured data — the GLEC gold standard
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Step 3: Fuel Consumption" icon="gas-pump" href="/guides/emissions/glec-step-3-fuel-consumption">
    Record actual fuel consumption for carrier-level accuracy
  </Card>

  <Card title="Step 4: GLEC Reports" icon="chart-pie" href="/guides/emissions/glec-step-4-reports">
    Generate your GLEC company report with hub emissions included
  </Card>
</CardGroup>