Create Commuting Period

Add a new commuting period for an employee to track transportation emissions

POST /v1/employee-historic

Create Commuting Period

JavaScript

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));

200

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

← Employees API

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 authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

employee_survey_id · string

The employee’s mobility survey this commute answers (for example, a pending survey filled in by hand). The survey’s row in the employees table becomes this response. Returns 404 (EMPLOYEE_SURVEY_NOT_FOUND) if it is not one of the employee’s surveys.

group_with_period_id · string

Another commuting period of the same survey response: this one joins it (a respondent who changed address or transport within the period). When that period answers no survey, an unsent one is created to group them. Returns 404 (SURVEY_RESPONSE_NOT_FOUND) if the period is not the employee’s.

Body Parameters

employee_id · string · required

UUID of the employee this period belongs to

Retrieve available options from GET /v2/employees

Example: "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 commute

Available values:

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

Example: "in_itinere"

transport_type · string · required

Mode of transportation

Available values: car, bus, train, metro, tram, motorbike, bicycle, walking, telecommuting, electric_kick_scooter, trolleybus

Example: "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, large

Example: "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_know

Example: "petrol"

renewable_energy · string

For electric vehicles/transport - whether powered by renewable energy

Available values: yes, no, do_not_know

Example: "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 status

Available values: active, inactive, terminated

Example: "active"

response_medium · string · required

How the commuting data was collected

Available values: manual, qr, form

Example: "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

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

Related Endpoints

Update Commuting Period

Modify period details

Delete Commuting Period

Remove a period

List Periods

View all periods

Employee Commuting Guide

Complete commuting tutorial