Skip to main content
POST
/
v1
/
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));
{
  "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

​
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

​
id
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