List Business Travels

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

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

import requests

url = "https://api.dcycle.io/v1/business-travels"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/business-travels \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {
    "id": "<string>",
    "organization_id": "<string>",
    "name": {},
    "email": {},
    "origin": {},
    "destination": {},
    "distance_km": {},
    "distance_source": {},
    "origin_geocode": {
      "origin_geocode.country_code": "<string>",
      "origin_geocode.place_id": "<string>",
      "origin_geocode.address_formatted": "<string>",
      "origin_geocode.latitude": 123,
      "origin_geocode.longitude": 123
    },
    "destination_geocode": {},
    "transport_type": "<string>",
    "travel_type": "<string>",
    "travel_number": 123,
    "passenger_number": 123,
    "start_date": "<string>",
    "end_date": "<string>",
    "vehicle_size": {},
    "fuel_type": {},
    "renewable_energy": {},
    "status": "<string>",
    "source": "<string>",
    "co2e": {},
    "file_id": {},
    "file_name": {},
    "uploaded_by": {
      "uploaded_by.id": "<string>",
      "uploaded_by.first_name": {},
      "uploaded_by.last_name": {},
      "uploaded_by.profile_img_url": {}
    },
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

GET

business-travels

List Business Travels

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

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

import requests

url = "https://api.dcycle.io/v1/business-travels"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/business-travels \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {
    "id": "<string>",
    "organization_id": "<string>",
    "name": {},
    "email": {},
    "origin": {},
    "destination": {},
    "distance_km": {},
    "distance_source": {},
    "origin_geocode": {
      "origin_geocode.country_code": "<string>",
      "origin_geocode.place_id": "<string>",
      "origin_geocode.address_formatted": "<string>",
      "origin_geocode.latitude": 123,
      "origin_geocode.longitude": 123
    },
    "destination_geocode": {},
    "transport_type": "<string>",
    "travel_type": "<string>",
    "travel_number": 123,
    "passenger_number": 123,
    "start_date": "<string>",
    "end_date": "<string>",
    "vehicle_size": {},
    "fuel_type": {},
    "renewable_energy": {},
    "status": "<string>",
    "source": "<string>",
    "co2e": {},
    "file_id": {},
    "file_name": {},
    "uploaded_by": {
      "uploaded_by.id": "<string>",
      "uploaded_by.first_name": {},
      "uploaded_by.last_name": {},
      "uploaded_by.profile_img_url": {}
    },
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

List Business Travels

Retrieve a paginated list of business travel records in your organization with support for filtering by transport type, status, and date range.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Query Parameters

array[string]

Filter by transport typeAvailable values: car, metro, train, trolleybus, bus, motorbike, aircraft, ferryExample: transport_type[]=train&transport_type[]=aircraft

array[string]

Filter by statusAvailable values: active, pending, loading, completed, errorExample: status[]=active

date

Filter by minimum travel date (inclusive)Format: YYYY-MM-DDExample: 2024-01-01

date

Filter by maximum travel date (inclusive)Format: YYYY-MM-DDExample: 2024-12-31

string

Search by name (case-insensitive substring match)Example: offsite

array[string]

Filter by exact name values (multi-select, OR logic)Example: name[]=Team offsite&name[]=Client visit

array[uuid]

Filter by source file UUID. Pass 00000000-0000-0000-0000-000000000000 to filter for records with no associated file.Example: file_id[]=3fa85f64-5717-4562-b3fc-2c963f66afa6

datetime

Filter records created on or after this timestamp (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ

datetime

Filter records created on or before this timestamp (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ

string

Filter by CO2e calculation statusAvailable values: calculated, not_calculated

string

Sort field. Prefix with - for descending order. Can be repeated for multi-sort.Available values: start_date, -start_date, end_date, -end_date, name, -name, created_at, -created_at, updated_at, -updated_atExample: -start_date

integer

default:"1"

Page number for paginationExample: 2

integer

default:"50"

Number of items per page (max 100)Example: 50

Response

array[object]

Array of business travel objects

Show Business Travel Object

string

Unique identifier (UUID)

string

Organization UUID

string | null

Travel record label

string | null

Traveler email

string | null

Starting location address

string | null

Ending location address

number | null

Distance traveled in kilometers

string | null

How the distance was obtained: manual (provided directly), geodesic (great-circle for aircraft), or google_maps (other transport types with origin/destination)

object | null

Geocoded origin location details (when available)

Show geocode fields

string

ISO country code

string

Place identifier

string

Formatted address

number

Latitude coordinate

number

Longitude coordinate

object | null

Geocoded destination location details (when available). Same structure as origin_geocode.

string

Mode of transport: car, metro, train, trolleybus, bus, motorbike, aircraft, ferry

string

Trip type: one_way or round

integer

Number of trips

integer

Number of passengers per trip

date

Travel start date

date

Travel end date

string | null

Vehicle size (car only): small, medium, large

string | null

Fuel type (car only): diesel, petrol, natural_gas, lpg, electric, hybrid, not_fuel_based, do_not_know

string | null

Renewable energy usage: yes, no, do_not_know

string

Current status: active, pending, loading, completed, error

string

How the record was created: manual, bulk_upload, form, api

number | null

Calculated CO2 equivalent emissions in kg

string | null

UUID of the source bulk-upload file, if any

string | null

Name of the source file, if any

object | null

The user who created this record

Show user fields

string

User UUID

string | null

First name

string | null

Last name

string | null

Profile image URL

datetime

Creation timestamp

datetime | null

Last update timestamp

integer

Total number of records matching the filter

integer

Current page number

integer

Number of items per page

string

Hash of the current filter state — use to detect if filters have changed

Example

curl -X GET "https://api.dcycle.io/v1/business-travels?page=1&size=50&status[]=active" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

response = requests.get(
    "https://api.dcycle.io/v1/business-travels",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    params={
        "page": 1,
        "size": 50,
        "status[]": ["active"],
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
    },
)

result = response.json()
print(f"Page {result['page']}, {result['total']} total records")
for travel in result["items"]:
    print(f"{travel['transport_type']}: {travel['origin']} -> {travel['destination']} ({travel['co2e']} kg CO2e)")

const axios = require('axios');

axios.get(
  'https://api.dcycle.io/v1/business-travels',
  {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
    params: {
      page: 1,
      size: 50,
      'status[]': ['active'],
      start_date: '2024-01-01',
      end_date: '2024-12-31',
    },
  }
)
.then(({ data }) => {
  console.log(`Page ${data.page}, ${data.total} total records`);
  data.items.forEach(travel => {
    console.log(`${travel.transport_type}: ${travel.origin} -> ${travel.destination} (${travel.co2e} kg CO2e)`);
  });
})
.catch(error => console.error(error));

Successful Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "name": "Madrid–Barcelona train",
      "email": null,
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "distance_km": 621.5,
      "distance_source": "google_maps",
      "origin_geocode": {
        "country_code": "ES",
        "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ",
        "address_formatted": "Madrid, Spain",
        "latitude": 40.4168,
        "longitude": -3.7038
      },
      "destination_geocode": {
        "country_code": "ES",
        "place_id": "ChIJ5TCOcRaYpBIRCmZHTz37sEQ",
        "address_formatted": "Barcelona, Spain",
        "latitude": 41.3874,
        "longitude": 2.1686
      },
      "transport_type": "train",
      "travel_type": "one_way",
      "travel_number": 2,
      "passenger_number": 1,
      "start_date": "2024-12-01",
      "end_date": "2024-12-01",
      "vehicle_size": null,
      "fuel_type": null,
      "renewable_energy": null,
      "status": "active",
      "source": "manual",
      "co2e": 24.86,
      "file_id": null,
      "file_name": null,
      "uploaded_by": {
        "id": "b9f1e2d3-0000-0000-0000-000000000001",
        "first_name": "Ana",
        "last_name": "García",
        "profile_img_url": null
      },
      "created_at": "2024-12-01T10:30:00Z",
      "updated_at": "2024-12-01T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "name": "Client meeting London",
      "email": null,
      "origin": "Madrid, Spain",
      "destination": "London, UK",
      "distance_km": 1250.0,
      "distance_source": "geodesic",
      "origin_geocode": null,
      "destination_geocode": null,
      "transport_type": "aircraft",
      "travel_type": "round",
      "travel_number": 1,
      "passenger_number": 1,
      "start_date": "2024-11-15",
      "end_date": "2024-11-15",
      "vehicle_size": null,
      "fuel_type": null,
      "renewable_energy": null,
      "status": "active",
      "source": "manual",
      "co2e": 385.5,
      "file_id": null,
      "file_name": null,
      "uploaded_by": {
        "id": "b9f1e2d3-0000-0000-0000-000000000001",
        "first_name": "Ana",
        "last_name": "García",
        "profile_img_url": null
      },
      "created_at": "2024-11-15T08:00:00Z",
      "updated_at": "2024-11-15T08:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "d4f9a2..."
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

404 Not Found

Cause: Organization not found

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

Use Cases

Paginate Through All Records

def get_all_business_travels(headers, **filters):
    """Paginate through all business travel records."""
    all_travels = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/business-travels",
            headers=headers,
            params={"page": page, "size": 100, **filters},
        )
        data = response.json()
        all_travels.extend(data["items"])

        if len(all_travels) >= data["total"]:
            break
        page += 1

    return all_travels

Group Emissions by Transport Type

from collections import defaultdict

travels = get_all_business_travels(
    headers,
    **{"status[]": ["active"], "start_date": "2024-01-01", "end_date": "2024-12-31"},
)

by_type = defaultdict(lambda: {"co2e": 0, "count": 0, "km": 0})
for t in travels:
    by_type[t["transport_type"]]["co2e"] += t["co2e"] or 0
    by_type[t["transport_type"]]["count"] += 1
    by_type[t["transport_type"]]["km"] += t["distance_km"] or 0

for t_type, data in sorted(by_type.items(), key=lambda x: -x[1]["co2e"]):
    print(f"{t_type}: {data['co2e']:.1f} kg CO2e, {data['km']:.0f} km ({data['count']} trips)")

Get Business Travel

Get a specific business travel by ID

Create Business Travel

Add a new business travel record

Update Business Travel

Modify business travel details

Delete Business Travel

Remove a business travel record

Business Travels API Get Totals

​List Business Travels

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Use Cases

​Paginate Through All Records

​Group Emissions by Transport Type

​Related Endpoints

Get Business Travel

Create Business Travel

Update Business Travel

Delete Business Travel

List Business Travels

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Use Cases

Paginate Through All Records

Group Emissions by Transport Type

Related Endpoints