Create Commuting Period

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    employee_id: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    commuting_type: '<string>',
    transport_type: '<string>',
    total_km: 123,
    weekly_travels: {},
    daily_trips: 123,
    vehicle_size: '<string>',
    fuel_type: '<string>',
    renewable_energy: '<string>',
    carpool: true,
    situation: '<string>',
    response_medium: '<string>'
  })
};

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

import requests

url = "https://api.dcycle.io/v1/employee-historic"

payload = {
    "employee_id": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "commuting_type": "<string>",
    "transport_type": "<string>",
    "total_km": 123,
    "weekly_travels": {},
    "daily_trips": 123,
    "vehicle_size": "<string>",
    "fuel_type": "<string>",
    "renewable_energy": "<string>",
    "carpool": True,
    "situation": "<string>",
    "response_medium": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employee-historic \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "employee_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "commuting_type": "<string>",
  "transport_type": "<string>",
  "total_km": 123,
  "weekly_travels": {},
  "daily_trips": 123,
  "vehicle_size": "<string>",
  "fuel_type": "<string>",
  "renewable_energy": "<string>",
  "carpool": true,
  "situation": "<string>",
  "response_medium": "<string>"
}
'

{
  "id": "<string>",
  "employee_id": "<string>",
  "co2e": 123
}

POST

employee-historic

Create Commuting Period

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    employee_id: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    commuting_type: '<string>',
    transport_type: '<string>',
    total_km: 123,
    weekly_travels: {},
    daily_trips: 123,
    vehicle_size: '<string>',
    fuel_type: '<string>',
    renewable_energy: '<string>',
    carpool: true,
    situation: '<string>',
    response_medium: '<string>'
  })
};

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

import requests

url = "https://api.dcycle.io/v1/employee-historic"

payload = {
    "employee_id": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "commuting_type": "<string>",
    "transport_type": "<string>",
    "total_km": 123,
    "weekly_travels": {},
    "daily_trips": 123,
    "vehicle_size": "<string>",
    "fuel_type": "<string>",
    "renewable_energy": "<string>",
    "carpool": True,
    "situation": "<string>",
    "response_medium": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employee-historic \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "employee_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "commuting_type": "<string>",
  "transport_type": "<string>",
  "total_km": 123,
  "weekly_travels": {},
  "daily_trips": 123,
  "vehicle_size": "<string>",
  "fuel_type": "<string>",
  "renewable_energy": "<string>",
  "carpool": true,
  "situation": "<string>",
  "response_medium": "<string>"
}
'

{
  "id": "<string>",
  "employee_id": "<string>",
  "co2e": 123
}

Create Commuting Period

Create a new commuting period for an employee. This defines how the employee commutes during a specific date range, enabling CO2e emissions calculations.

Transport Type Rules: Different transport types require different field combinations. See the transport validation rules below.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Body Parameters

string

required

UUID of the employee this period belongs toExample: "550e8400-e29b-41d4-a716-446655440000"

date

required

Period start date (YYYY-MM-DD)Example: "2024-01-01"

date

required

Period end date (YYYY-MM-DD). Must be after start_date.Example: "2024-12-31"

string

required

Type of commuteAvailable values:

in_itinere - Home to work commute (daily commuting)
in_labore - Travel during work hours

Example: "in_itinere"

string

required

Mode of transportationAvailable values: car, bus, train, metro, tram, motorbike, bicycle, walking, telecommuting, electric_kick_scooter, trolleybusExample: "car"

number

One-way distance in kilometers. Required for all transport types except telecommuting.Example: 15

array[integer]

Days of the week the employee commutes (0=Monday, 6=Sunday). Required for all transport types except telecommuting.Example: [0, 1, 2, 3, 4] (Monday to Friday)

integer

required

Number of round trips per day (usually 1)Example: 1

string

Vehicle size (required for car transport type)Available values: small, medium, largeExample: "medium"

string

Fuel type. Required for car, bus, motorbike. Optional for train, metro, bicycle, trolleybus.Available values: petrol, diesel, electric, hybrid, lpg, natural_gas, not_fuel_based, do_not_knowExample: "petrol"

string

For electric vehicles/transport - whether powered by renewable energyAvailable values: yes, no, do_not_knowExample: "yes"

boolean

required

Whether the employee carpools. Must be true or false for car, must be false for other transport types.Example: false

string

required

Period statusAvailable values: active, inactive, terminatedExample: "active"

string

required

How the commuting data was collectedAvailable values: manual, qr, formExample: "manual"

Transport Validation Rules

When providing transport fields, all related fields must be provided together:

Car

{
  "transport_type": "car",
  "vehicle_size": "small|medium|large",  // required
  "fuel_type": "petrol|diesel|electric|hybrid|lpg|natural_gas|do_not_know",  // required
  "carpool": true|false,  // required
  "renewable_energy": "yes|no|do_not_know"  // only if fuel_type is "electric"
}

Bus

{
  "transport_type": "bus",
  "vehicle_size": null,
  "fuel_type": "diesel|natural_gas|petrol|lpg|do_not_know",  // required
  "carpool": false,
  "renewable_energy": null
}

Train / Metro / Trolleybus

{
  "transport_type": "train|metro|trolleybus",
  "vehicle_size": null,
  "fuel_type": "electric|do_not_know",  // optional
  "carpool": false,
  "renewable_energy": "yes|no|do_not_know"  // only if fuel_type is "electric"
}

Motorbike

{
  "transport_type": "motorbike",
  "vehicle_size": null,
  "fuel_type": "diesel|petrol|electric|do_not_know",  // required
  "carpool": false,
  "renewable_energy": "yes|no|do_not_know"  // only if fuel_type is "electric"
}

Bicycle

{
  "transport_type": "bicycle",
  "vehicle_size": null,
  "fuel_type": "electric|not_fuel_based|do_not_know",  // optional
  "carpool": false,
  "renewable_energy": "yes|no|do_not_know"  // only if fuel_type is "electric"
}

Walking / Tram / Electric Kick Scooter / Telecommuting

{
  "transport_type": "walking|tram|electric_kick_scooter|telecommuting",
  "vehicle_size": null,
  "fuel_type": null,
  "carpool": false,
  "renewable_energy": null
}

Response

string

Unique identifier (UUID)

string

Employee UUID

number

Calculated CO2 equivalent emissions in kg for the period

All other fields mirror the request body.

Example

curl -X POST "https://api.dcycle.io/v1/employee-historic" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "550e8400-e29b-41d4-a716-446655440000",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "commuting_type": "in_itinere",
    "transport_type": "car",
    "vehicle_size": "medium",
    "fuel_type": "petrol",
    "renewable_energy": null,
    "total_km": 15,
    "weekly_travels": [0, 1, 2, 3, 4],
    "daily_trips": 1,
    "carpool": false,
    "situation": "active",
    "response_medium": "manual"
  }'

import requests
import os

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

payload = {
    "employee_id": "550e8400-e29b-41d4-a716-446655440000",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "commuting_type": "in_itinere",
    "transport_type": "car",
    "vehicle_size": "medium",
    "fuel_type": "petrol",
    "renewable_energy": None,
    "total_km": 15,
    "weekly_travels": [0, 1, 2, 3, 4],
    "daily_trips": 1,
    "carpool": False,
    "situation": "active",
    "response_medium": "manual"
}

response = requests.post(
    "https://api.dcycle.io/v1/employee-historic",
    headers=headers,
    json=payload
)

period = response.json()
print(f"Period created: {period['id']}")
print(f"CO2e: {period['co2e']} kg")

const axios = require('axios');

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

const payload = {
  employee_id: '550e8400-e29b-41d4-a716-446655440000',
  start_date: '2024-01-01',
  end_date: '2024-12-31',
  commuting_type: 'in_itinere',
  transport_type: 'car',
  vehicle_size: 'medium',
  fuel_type: 'petrol',
  renewable_energy: null,
  total_km: 15,
  weekly_travels: [0, 1, 2, 3, 4],
  daily_trips: 1,
  carpool: false,
  situation: 'active',
  response_medium: 'manual'
};

axios.post(
  'https://api.dcycle.io/v1/employee-historic',
  payload,
  { headers }
)
.then(response => {
  const period = response.data;
  console.log(`Period created: ${period.id}`);
  console.log(`CO2e: ${period.co2e} kg`);
});

Successful Response

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "employee_id": "550e8400-e29b-41d4-a716-446655440000",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "commuting_type": "in_itinere",
  "transport_type": "car",
  "vehicle_size": "medium",
  "fuel_type": "petrol",
  "renewable_energy": null,
  "total_km": 15,
  "weekly_travels": [0, 1, 2, 3, 4],
  "daily_trips": 1,
  "carpool": false,
  "situation": "active",
  "origin": null,
  "destination": null,
  "response_medium": "manual",
  "co2e": 1245.5,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}

Common Errors

422 Validation Error

Cause: Invalid field combinations

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "When providing transport_type 'car', vehicle_size must also be provided",
      "type": "value_error"
    }
  ]
}

Solution: Ensure all required fields for the transport type are provided.

404 Not Found

Cause: Employee not found

{
  "code": "EMPLOYEE_NOT_FOUND",
  "detail": "Employee with id=UUID('...') not found"
}

Use Cases

Create Car Commute

car_period = {
    "employee_id": employee_id,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "commuting_type": "in_itinere",
    "transport_type": "car",
    "vehicle_size": "medium",
    "fuel_type": "diesel",
    "renewable_energy": None,
    "total_km": 20,
    "weekly_travels": [0, 1, 2, 3, 4],
    "daily_trips": 1,
    "carpool": False,
    "situation": "active",
    "response_medium": "manual"
}

Create Public Transit Commute

train_period = {
    "employee_id": employee_id,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "commuting_type": "in_itinere",
    "transport_type": "train",
    "vehicle_size": None,
    "fuel_type": "electric",
    "renewable_energy": "yes",
    "total_km": 30,
    "weekly_travels": [1, 2, 3],  # Tue, Wed, Thu
    "daily_trips": 1,
    "carpool": False,
    "situation": "active",
    "response_medium": "manual"
}

Create Remote Worker Period

remote_period = {
    "employee_id": employee_id,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "commuting_type": "in_itinere",
    "transport_type": "telecommuting",
    "vehicle_size": None,
    "fuel_type": None,
    "renewable_energy": None,
    "total_km": None,
    "weekly_travels": [],  # Empty = no commuting
    "daily_trips": 0,
    "carpool": False,
    "situation": "active",
    "response_medium": "manual"
}

Create Carpool Commute

carpool_period = {
    "employee_id": employee_id,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "commuting_type": "in_itinere",
    "transport_type": "car",
    "vehicle_size": "large",
    "fuel_type": "petrol",
    "renewable_energy": None,
    "total_km": 25,
    "weekly_travels": [0, 1, 2, 3, 4],
    "daily_trips": 1,
    "carpool": True,  # Emissions divided by 3
    "situation": "active",
    "response_medium": "manual"
}

Update Commuting Period

Modify period details

Delete Commuting Period

Remove a period

List Periods

View all periods

Employee Commuting Guide

Complete commuting tutorial

​Create Commuting Period

​Request

​Headers

​Body Parameters

​Transport Validation Rules

​Car

​Bus

​Train / Metro / Trolleybus

​Motorbike

​Bicycle

​Walking / Tram / Electric Kick Scooter / Telecommuting

​Response

​Example

​Successful Response

​Common Errors

​422 Validation Error

​404 Not Found

​Use Cases

​Create Car Commute

​Create Public Transit Commute

​Create Remote Worker Period

​Create Carpool Commute

​Related Endpoints

Update Commuting Period

Delete Commuting Period

List Periods

Employee Commuting Guide

Create Commuting Period

Request

Headers

Body Parameters

Transport Validation Rules

Car

Bus

Train / Metro / Trolleybus

Motorbike

Bicycle

Walking / Tram / Electric Kick Scooter / Telecommuting

Response

Example

Successful Response

Common Errors

422 Validation Error

404 Not Found

Use Cases

Create Car Commute

Create Public Transit Commute

Create Remote Worker Period

Create Carpool Commute

Related Endpoints