List Facilities

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/facilities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/facilities"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/facilities \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {
    "id": "<string>",
    "name": "<string>",
    "address": {},
    "country": "<string>",
    "type": "<string>",
    "status": "<string>",
    "co2e": {},
    "co2e_biomass": {},
    "logistic_factor": {},
    "categories": {},
    "cups_list": {},
    "facility_purpose_type": {},
    "created_at": {},
    "updated_at": {},
    "invoices_in_review_count": 123,
    "categories_without_data": 123,
    "water_type": {},
    "methane_burned": {},
    "wwt_line": {
      "id": "<string>",
      "line_code": "<string>"
    },
    "sludge_line": {
      "id": "<string>",
      "line_code": "<string>"
    },
    "wwd_line": {
      "id": "<string>",
      "line_code": "<string>"
    }
  },
  "total": 123,
  "page": 123,
  "size": 123
}

GET

facilities

List Facilities

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/facilities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/facilities"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/facilities \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {
    "id": "<string>",
    "name": "<string>",
    "address": {},
    "country": "<string>",
    "type": "<string>",
    "status": "<string>",
    "co2e": {},
    "co2e_biomass": {},
    "logistic_factor": {},
    "categories": {},
    "cups_list": {},
    "facility_purpose_type": {},
    "created_at": {},
    "updated_at": {},
    "invoices_in_review_count": 123,
    "categories_without_data": 123,
    "water_type": {},
    "methane_burned": {},
    "wwt_line": {
      "id": "<string>",
      "line_code": "<string>"
    },
    "sludge_line": {
      "id": "<string>",
      "line_code": "<string>"
    },
    "wwd_line": {
      "id": "<string>",
      "line_code": "<string>"
    }
  },
  "total": 123,
  "page": 123,
  "size": 123
}

List Facilities

Retrieve a paginated list of facilities in your organization with support for filtering by name, country, type, and status.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

string

Filter facilities by name (partial match, case-insensitive)Example: "Madrid"

string

Filter by ISO country codeExample: "ES"

string

Filter by facility typeExample: "office"

array[string]

Filter by facility statusAvailable values: active, archivedExample: status[]=active

string

Compound filter expression for advanced filtering. Format: field:value with | for OR.Example: name:Madrid|name:Barcelona

integer

default:"1"

Page number for pagination

integer

default:"10"

Number of items per page (max 100)

Response

array[object]

Array of facility objects

Show Facility Object

string

Unique identifier (UUID)

string

Facility name

string | null

Physical address

string

ISO country code

string

Facility type

string

Status: active or archived

number | null

CO2e emissions in kg

number | null

CO2e from biomass

number | null

Logistic factor (0-1)

array[string] | null

Consumption categories

array[string] | null

CUPS codes

string | null

Purpose type

datetime

Creation timestamp

datetime | null

Last update timestamp

integer

Number of enabled invoices linked to this facility with status='review', across all categories (electricity, water, heat, recharge). Defaults to 0.

integer

Number of configured consumption categories that have no enabled invoices. Defaults to 0.

string | null

Water type of the waste water treatment line (only for waste_water_facilities)

boolean | null

Whether methane is burned (only for waste_water_facilities)

object | null

Waste water treatment line config (only for waste_water_facilities)

Show WWT Line Object

string

Line UUID

string

Line code identifier

object | null

Sludge treatment line config (only for waste_water_facilities)

Show Sludge Line Object

string

Line UUID

string

Line code identifier

object | null

Water discharge line config (only for waste_water_facilities)

Show WWD Line Object

string

Line UUID

string

Line code identifier

integer

Total number of facilities matching the filter

integer

Current page number

integer

Number of items per page

Example

curl -X GET "https://api.dcycle.io/v1/facilities?page=1&size=50&status[]=active" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

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={"page": 1, "size": 50, "status[]": ["active"]}
)

for facility in response.json()["items"]:
    print(f"{facility['name']}: {facility['co2e'] or 0} kg CO2e")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID
};

axios.get('https://api.dcycle.io/v1/facilities', {
  headers,
  params: { page: 1, size: 50, 'status[]': ['active'] }
})
.then(response => {
  response.data.items.forEach(f => {
    console.log(`${f.name}: ${f.co2e || 0} kg CO2e`);
  });
});

Successful Response

{
  "items": [
    {
      "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",
      "invoices_in_review_count": 2,
      "categories_without_data": 0,
      "water_type": null,
      "methane_burned": null,
      "wwt_line": null,
      "sludge_line": null,
      "wwd_line": null
    }
  ],
  "total": 12,
  "page": 1,
  "size": 50
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

Create Facility

Add a new facility

Get Facility

Retrieve a single facility

Facilities API Get Facility

​List Facilities

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​Related Endpoints

Create Facility

Get Facility

List Facilities

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

Related Endpoints