Update Commuting Period

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

fetch('https://api.dcycle.io/v1/employee-historic/{employee_historic_id}', 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/{employee_historic_id}"

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

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

print(response.text)

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

{
  "id": "<string>",
  "employee_id": "<string>",
  "start_date": "<string>",
  "end_date": {},
  "commuting_type": "<string>",
  "transport_type": {},
  "vehicle_size": {},
  "fuel_type": {},
  "renewable_energy": {},
  "carpool": true,
  "total_km": {},
  "weekly_travels": {},
  "daily_trips": 123,
  "situation": {},
  "origin": {},
  "destination": {},
  "response_medium": {},
  "co2e": {},
  "created_at": {},
  "updated_at": {}
}

PATCH

employee-historic

{employee_historic_id}

Update Commuting Period

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

fetch('https://api.dcycle.io/v1/employee-historic/{employee_historic_id}', 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/{employee_historic_id}"

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

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

print(response.text)

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

{
  "id": "<string>",
  "employee_id": "<string>",
  "start_date": "<string>",
  "end_date": {},
  "commuting_type": "<string>",
  "transport_type": {},
  "vehicle_size": {},
  "fuel_type": {},
  "renewable_energy": {},
  "carpool": true,
  "total_km": {},
  "weekly_travels": {},
  "daily_trips": 123,
  "situation": {},
  "origin": {},
  "destination": {},
  "response_medium": {},
  "co2e": {},
  "created_at": {},
  "updated_at": {}
}

Update Commuting Period

Update an existing commuting period. You can modify transport details, dates, or other attributes. The CO2e will be recalculated automatically.

Transport Field Groups: When updating transport-related fields (transport_type, vehicle_size, fuel_type, renewable_energy, carpool), you must provide all five fields together.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Path Parameters

string

required

The unique identifier (UUID) of the commuting periodExample: 660e8400-e29b-41d4-a716-446655440000

Body Parameters

All parameters are optional. Only include fields you want to update.

date

Period start date. Must provide end_date as well.

date

Period end date. Must provide start_date as well.

string

Type: in_itinere or in_labore

string

Mode of transport. When provided, must include all transport fields.

string

Vehicle size for cars. Part of transport field group.

string

Fuel type. Part of transport field group.

string

Renewable energy source. Part of transport field group.

boolean

Carpooling status. Part of transport field group.

number

One-way distance in kilometers.

array[integer]

Days of week for commuting.

integer

Round trips per day.

string

Period status: active, inactive, terminated

Response

Returns the updated commuting period with recalculated CO2e.

string

Commuting period UUID

string

Parent employee UUID

date

Period start date (YYYY-MM-DD)

string | null

Period end date (YYYY-MM-DD)

string

in_itinere (home-to-office) or in_labore (work-related travel)

string | null

Mode of transport (e.g. car, train, bicycle, bus)

string | null

Vehicle size category

string | null

Fuel type

string | null

Renewable energy source

boolean

Whether the employee carpools

number | null

One-way distance in kilometers

array[integer] | null

Days of the week the employee commutes (0=Monday, 6=Sunday)

integer

Round trips per commuting day

string | null

Period status: active, inactive, terminated

string | null

Origin address

string | null

Destination address

string | null

How the data was collected (e.g. manual, survey, csv)

number | null

Calculated CO2 equivalent emissions in kg

string | null

ISO 8601 creation timestamp

string | null

ISO 8601 last update timestamp

Example

curl -X PATCH "https://api.dcycle.io/v1/employee-historic/660e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "transport_type": "train",
    "vehicle_size": null,
    "fuel_type": "electric",
    "renewable_energy": "yes",
    "carpool": false
  }'

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

period_id = "660e8400-e29b-41d4-a716-446655440000"

# Change from car to train
payload = {
    "transport_type": "train",
    "vehicle_size": None,
    "fuel_type": "electric",
    "renewable_energy": "yes",
    "carpool": False
}

response = requests.patch(
    f"https://api.dcycle.io/v1/employee-historic/{period_id}",
    headers=headers,
    json=payload
)

period = response.json()
print(f"Updated transport: {period['transport_type']}")
print(f"New 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 periodId = '660e8400-e29b-41d4-a716-446655440000';

// Change from car to train
const payload = {
  transport_type: 'train',
  vehicle_size: null,
  fuel_type: 'electric',
  renewable_energy: 'yes',
  carpool: false
};

axios.patch(
  `https://api.dcycle.io/v1/employee-historic/${periodId}`,
  payload,
  { headers }
)
.then(response => {
  const period = response.data;
  console.log(`Updated transport: ${period.transport_type}`);
  console.log(`New 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": "train",
  "vehicle_size": null,
  "fuel_type": "electric",
  "renewable_energy": "yes",
  "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": 312.4,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-11-24T14:45:00Z"
}

Common Errors

422 Validation Error

Cause: Partial transport field update

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "When providing any transport field, all fields must be provided. Missing: vehicle_size, carpool",
      "type": "value_error"
    }
  ]
}

Solution: Include all transport fields: transport_type, vehicle_size, fuel_type, renewable_energy, carpool.

Use Cases

Update Distance

# Just update the distance
payload = {"total_km": 20}

Change Working Days

# Switch to hybrid (3 days/week)
payload = {"weekly_travels": [1, 2, 3]}

Update Date Range

# Both dates required together
payload = {
    "start_date": "2024-07-01",
    "end_date": "2024-12-31"
}

Switch Transport Mode

# All transport fields required together
payload = {
    "transport_type": "bicycle",
    "vehicle_size": None,
    "fuel_type": "not_fuel_based",
    "renewable_energy": None,
    "carpool": False
}

Create Period

Add new period

Delete Period

Remove period

Create Commuting Period Delete Commuting Period

​Update Commuting Period

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​422 Validation Error

​Use Cases

​Update Distance

​Change Working Days

​Update Date Range

​Switch Transport Mode

​Related Endpoints

Create Period

Delete Period

Update Commuting Period

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

422 Validation Error

Use Cases

Update Distance

Change Working Days

Update Date Range

Switch Transport Mode

Related Endpoints