List Facilities

Retrieve all facilities registered in your organization with pagination support and flexible filtering options.

This endpoint excludes logistics hubs from results. Logistics hubs are special facility types used for warehouse and distribution center operations.

Request

Headers

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

x-user-id

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Query Parameters

page

integer

default:"1"

Page number for paginationExample: 1

size

integer

default:"50"

Number of items per page (max: 100)Example: 50

name

string

Filter facilities by name (partial match)Example: "Madrid Office"

start_date

integer

Filter by creation date start (Unix timestamp)Example: 1704067200 (January 1, 2024)

end_date

integer

Filter by creation date end (Unix timestamp)Example: 1735689600 (January 1, 2025)

filter_by

string

Advanced filtering criteria (format: field:value)Example: "country:ES"

sort_by

string

Sort criteria (format: field:asc or field:desc)Example: "name:asc"

Response

page

integer

Current page number

size

integer

Number of items per page

total

integer

Total count of active facilities (excluding logistics hubs)

total2

integer

Total count of archived facilities (excluding logistics hubs)

items

array

Array of facility objects

Facility Object Fields:

id (string, UUID) - Unique facility identifier
name (string) - Facility name
country (string) - ISO 3166-1 alpha-2 country code
type (string) - Facility type
address (string, optional) - Full address
logistic_factor (float, optional) - Logistic efficiency factor (0.0 - 1.0)
categories (array of strings, optional) - Facility categories
cups_list (array of strings, optional) - CUPS codes for electricity meters
status (string) - "active" or "archived"
facility_fuels_ids (array of strings, optional) - Associated fuel IDs
co2e (float) - Total CO2 equivalent emissions in kg
co2e_biomass (float, optional) - Biomass CO2 emissions in kg
invoices_length (integer, optional) - Number of invoices
invoices_in_review_count (integer) - Number of enabled invoices with status='review' for this facility, across all categories (electricity, water, heat, recharge). Defaults to 0.
created_at (datetime) - Creation timestamp
updated_at (datetime) - Last update timestamp
facility_purpose_type (string) - Purpose classification
supercharger (boolean, optional) - Electric vehicle supercharger available
facility_id (string, optional) - External facility identifier
hub_category (string, optional) - Logistics hub category (null for regular facilities)

Example

curl -X GET "https://api.dcycle.io/api/v1/facilities?page=1&size=50&name=Madrid" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

Successful Response

{
  "page": 1,
  "size": 50,
  "total": 15,
  "total2": 3,
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Madrid Central Office",
      "country": "ES",
      "type": "office",
      "address": "Calle Gran Vía 123, Madrid, Spain",
      "logistic_factor": 0.8,
      "categories": ["headquarters", "admin"],
      "cups_list": ["ES0031406398765432GH0F"],
      "status": "active",
      "facility_fuels_ids": [],
      "co2e": 12450.5,
      "co2e_biomass": 0.0,
      "invoices_length": 24,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-11-20T14:22:00Z",
      "facility_purpose_type": "operational",
      "supercharger": true,
      "facility_id": "FAC-2024-001",
      "hub_category": null
    },
    {
      "id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
      "name": "Barcelona Production Plant",
      "country": "ES",
      "type": "production",
      "address": "Polígono Industrial Can Salvatella, Barcelona, Spain",
      "logistic_factor": 0.75,
      "categories": ["manufacturing", "production"],
      "cups_list": ["ES0031406398765433AB1G"],
      "status": "active",
      "facility_fuels_ids": ["fuel-id-1", "fuel-id-2"],
      "co2e": 45320.8,
      "co2e_biomass": 1250.0,
      "invoices_length": 48,
      "created_at": "2023-06-10T08:15:00Z",
      "updated_at": "2024-11-18T09:45:00Z",
      "facility_purpose_type": "industrial",
      "supercharger": false,
      "facility_id": "FAC-2023-045",
      "hub_category": null
    }
  ]
}

Common Errors

400 Bad Request

Cause: Invalid query parameters or date format

{
  "detail": "Invalid date format",
  "code": "VALIDATION_ERROR"
}

Solution: Verify that dates are Unix timestamps (integers) and pagination parameters are positive integers.

403 Forbidden

Cause: Organization ID doesn’t match your API key or user doesn’t belong to organization

{
  "detail": "Not authorized",
  "code": "FORBIDDEN"
}

Solution: Verify that x-organization-id matches your API key’s organization.

Use Cases

Facility Dashboard

Display all active facilities with emissions:

def get_facilities_dashboard():
    """Get facilities for dashboard display"""
    response = requests.get(
        "https://api.dcycle.io/api/v1/facilities",
        headers=headers,
        params={"page": 1, "size": 100, "sort_by": "co2e:desc"}
    )

    facilities = response.json()

    # Calculate totals
    total_emissions = sum(f['co2e'] for f in facilities['items'])

    return {
        'facilities': facilities['items'],
        'total_active': facilities['total'],
        'total_archived': facilities['total2'],
        'total_emissions': total_emissions
    }

Filter by Country

Get all facilities in a specific country:

def get_facilities_by_country(country_code):
    """Get facilities filtered by country"""
    response = requests.get(
        "https://api.dcycle.io/api/v1/facilities",
        headers=headers,
        params={
            "filter_by": f"country:{country_code}",
            "page": 1,
            "size": 100
        }
    )

    facilities = response.json()

    print(f"Facilities in {country_code}: {facilities['total']}")
    for facility in facilities['items']:
        print(f"  - {facility['name']}: {facility['co2e']:.2f} kg CO2e")

    return facilities

# Example: Get all Spanish facilities
spanish_facilities = get_facilities_by_country("ES")

Date Range Query

Get facilities created within a specific time period:

from datetime import datetime, timedelta

def get_recent_facilities(days=30):
    """Get facilities created in the last N days"""
    end_date = int(datetime.now().timestamp())
    start_date = int((datetime.now() - timedelta(days=days)).timestamp())

    response = requests.get(
        "https://api.dcycle.io/api/v1/facilities",
        headers=headers,
        params={
            "start_date": start_date,
            "end_date": end_date,
            "sort_by": "created_at:desc"
        }
    )

    facilities = response.json()

    print(f"Facilities created in last {days} days: {len(facilities['items'])}")
    return facilities

# Get facilities from last 30 days
recent = get_recent_facilities(30)

Pagination

When you have many facilities, use pagination to retrieve all results:

def get_all_facilities():
    """Fetch all facilities with pagination"""
    all_facilities = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/api/v1/facilities",
            headers=headers,
            params={"page": page, "size": 100}
        )

        data = response.json()
        all_facilities.extend(data['items'])

        # Check if we've retrieved all items
        if len(all_facilities) >= data['total']:
            break

        page += 1

    return all_facilities

# Get all facilities at once
all_facilities = get_all_facilities()
print(f"Total facilities retrieved: {len(all_facilities)}")

Special Notes

Logistics Hubs Exclusion

This endpoint automatically excludes logistics hubs from results. Logistics hubs are special facility types with a hub_category field set to one of:

transshipment_ambient
transshipment_mixed
storage_transhipment_ambient
storage_transhipment_mixed
warehouse_ambient
warehouse_mixed
liquid_bulk_terminals_ambient
liquid_bulk_terminals_mixed
maritime_container_terminals_ambient
maritime_container_terminals_temperature_controlled

To access logistics hubs, use the dedicated logistics hubs endpoint (if available).

CO2e Field

The co2e field represents the total carbon footprint of the facility calculated from all invoices (electricity, heat, water, etc.). A value of 0.0 means either:

No invoices have been registered yet
All invoices have zero emissions
Calculations are pending

CUPS Codes

For Spanish facilities, cups_list contains electricity meter identifiers (Código Universal del Punto de Suministro). These are automatically populated when creating electricity invoices.

Create Invoice

Add consumption data to facilities

List Vehicles

View your vehicle fleet

Bulk Upload

Upload multiple facilities via CSV

Authentication

Learn about API authentication

​List Facilities

​Request

​Headers

​Query Parameters

​Response

​Facility Object Fields:

​Example

​Successful Response

​Common Errors

​400 Bad Request

​403 Forbidden

​Use Cases

​Facility Dashboard

​Filter by Country

​Date Range Query

​Pagination

​Special Notes

​Logistics Hubs Exclusion

​CO2e Field

​CUPS Codes

​Related Endpoints

Create Invoice

List Vehicles

Bulk Upload

Authentication

List Facilities

Request

Headers

Query Parameters

Response

Facility Object Fields:

Example

Successful Response

Common Errors

400 Bad Request

403 Forbidden

Use Cases

Facility Dashboard

Filter by Country

Date Range Query

Pagination

Special Notes

Logistics Hubs Exclusion

CO2e Field

CUPS Codes

Related Endpoints