Skip to main content

​
Facilities API

The Facilities API allows you to create, retrieve, update, and delete facilities within your organization. Each facility represents a physical site (office, warehouse, factory, etc.) and tracks energy consumption and CO2e emissions.
New API: This endpoint is part of the new API architecture with improved design and maintainability.

​
Key Features

  • Site Management: Create and manage facilities in your organization
  • Consumption Categories: Configure which consumption types apply to each facility (heat, electricity, water, recharge)
  • CO2e Tracking: Automatic emissions calculation based on facility consumption data
  • Regional Support: ISO country codes for region-specific emission factors
  • CUPS Integration: Associate electricity supply point codes (CUPS) with facilities
  • Pagination Support: Efficiently retrieve large lists of facilities

​
Authentication

All endpoints require authentication using either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef

​
Available Endpoints

List Facilities

Retrieve all facilities with filtering and pagination

Get Facility

Retrieve a single facility by ID

Create Facility

Add a new facility to your organization

Update Facility

Modify facility details

Delete Facility

Remove a facility from your organization

​
Facility Attributes

​
Core Information

  • name (string, required): Name of the facility (e.g., “Madrid Office”, “Barcelona Warehouse”)
  • type (string, required): Type of facility (e.g., “office”, “warehouse”, “factory”)
  • country (string, required): ISO 3166-1 country code (e.g., “ES”, “FR”, “DE”)
  • address (string, optional): Physical address of the facility

​
Configuration

  • categories (array[string], optional): Consumption categories enabled for this facility (e.g., ["heat", "electricity", "water", "recharge"])
  • cups_list (array[string], optional): List of CUPS (electricity supply point) codes associated with the facility
  • logistic_factor (float, optional): Logistic factor for scope 2 calculation in logistics reports (0 to 1, default 0.8)

​
Emission Data

  • co2e (float, read-only): Total CO2 equivalent emissions in kg CO2e
  • co2e_biomass (float, read-only): CO2e from biomass sources
  • status (string): Current status: active or archived

​
Response Format

​
Facility Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Madrid Office",
  "type": "office",
  "country": "ES",
  "address": "Calle Gran Vía 1, Madrid",
  "status": "active",
  "co2e": 1250.5,
  "co2e_biomass": 0.0,
  "logistic_factor": 0.8,
  "categories": ["heat", "electricity", "water"],
  "cups_list": ["ES0021000000000001AA"],
  "facility_purpose_type": "facilities",
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
201Created-
204No Content (delete successful)-
401UnauthorizedVerify API key or JWT token
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Use Cases

​
Track Office Emissions

Monitor CO2e emissions for all offices in your organization: 
import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID")
}

response = requests.get(
    "https://api.dcycle.io/v1/facilities",
    headers=headers,
    params={"status[]": ["active"], "type": "office"}
)

total_co2e = sum(f["co2e"] or 0 for f in response.json()["items"])
print(f"Total office emissions: {total_co2e} kg CO2e")

Authentication Guide

Learn how to get your API key and authenticate requests

Invoices API

Manage energy invoices linked to facilities