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

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

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

Body Parameters

employee_id

string

required

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

start_date

date

required

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

end_date

date

required

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

commuting_type

string

required

Type of commuteAvailable values:

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

Example: "in_itinere"

transport_type

string

required

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

total_km

number

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

weekly_travels

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)

daily_trips

integer

required

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

vehicle_size

string

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

fuel_type

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"

renewable_energy

string

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

carpool

boolean

required

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

situation

string

required

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

response_medium

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)

employee_id

string

Employee UUID

co2e

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"
  }'

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

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Business Travels

Employees

Commuting Periods

Create Commuting Period

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

Update Commuting Period

Delete Commuting Period

List Periods

Employee Commuting Guide

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Business Travels

Employees

Commuting Periods

​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