> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctechnology.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get trips
> Gets trips that a user has access to. The trips are always ordered by their
ending timestamp, newest one first. Use a `limit` query parameter to bound
the number of trips returned.
## OpenAPI
````yaml api-reference/openapi.yml get /trip
openapi: 3.0.3
info:
version: v2.2.0
title: c.technology vehicle REST API v2.2.0
description: >
## Introduction
The c.technology vehicle REST API provides the ability to programmatically
manage
and interact with the full range of c.technology products and services.
This documentation is auto-generated from our
[OpenAPI](https://www.openapis.org)
specification, which you can download
[by clicking here](https://docs.ctechnology.io/ctechnology-openapi.yml).
You can use this specification for example to automatically generate
libraries
in your favorite programming language.
In case you are using a JS / TS-compatible system, you can use our official
TypeScript
c.technology app builder SDK that essentially provides a reactive Redux
store out
of the box that features automatic loading from the c.technology backend as
well
as real-time updates on changes.
Concerning the latter, note that many endpoints are also available via the
c.technology
real-time (RT) API that can be found under docs.ctechnology.io/rt.
## Examples & inspirations
You can find many examples under
docs.ctechnology.io/code-examples or on the
[c.technology GitHub organization](https://github.com/c-technology).
## Versioning
The c.technology API is versioned, where the version identifier is part of
the URL:
`https://api.ctechnology.io/v2.2/...`. To make api requests, you do not have
to specify the
patch version (i.e., `v2.2` suffices, `v2.2.0` is not required), as the API
is backwards-compatible
between patch versions. Currently, the most up-do-date version is `v2.2.0`.
## Access and authentication
Most of our endpoints either require using a personal access token or a
programmatic / organizational
access token (that can be created from your admin panel and whose
permissions can
be managed from there). You can request a personal access token via the
login endpoint.
The access tokens must be sent as part of the HTTP `Authorization` header in
the
following form: `Authorization: Token {your_token}`, where you should
replace
`your_token` with the token you received after logging in or after creating
a
programmatic access.
Currently, we do not support OpenID, OAuth or similar login / access
schemes,
nor two-factor authentication.
## Requests
All requests must be made over HTTPS, if you use HTTP you will automatically
be
redirected to the respective HTTPS endpoint. We follow the general
convention
of HTTP RESTful endpoints:
| Method |
Usage
|
| -------------
|:---------------------------------------------------------------------------------------------------------|
| GET | Retrieve data about (collections of) resources.
Idempotent. |
| POST | Create new resources (on collection endpoints). Perform
operations/actions (on ops endpoints). |
| PUT | Modify existing
resources.
|
| DELETE | Delete existing resources. Depending on the endpoint, this
might also simply set a deleted flag to true. |
In general, there are several types of endpoints (we do not strictly enforce
this,
but it can serve you as a guideline in determining what an endpoint will
do):
- Endpoints ending in an ID of a resource return only this resource.
- Endpoints ending in a slash (irrespective if they contain an ID of a
resource
somewhere in the path) return a collection of resources. Often, leaving
away the resource ID at the end of a path will instead return all the
resources of this type that the user has access to (potentially filtered
and/or paginated, see below).
- GET endpoints should never lead to changes on the cloud system / database,
i.e.,
they are idempotent and can be called as many times as needed.
- If a path contains `/ops/`, it is an operation, i.e., calling this
endpoint
(usually with POST as it will lead to a change) will not result in a meaningful
response, but instead execute some operation in the c.technology cloud system.
By default, all communication is using `application/json` as a content type.
## Responses
The responses given by the c.technology cloud system follow standard HTTP
REST
conventions.
In particular, we return the following status codes:
| Status |
Description
|
| -------------------------
|:--------------------------------------------------------------------------------------------|
| 200 OK | Request successful, response contains
requested data. |
| 202 Accepted | Request successful, but processing is not
completed yet. |
| 204 No content | Request successful, but there is nothing to
return (e.g., often for `/ops`). |
| 400 Bad request | The request is invalid (bad formatting,
missing parameters, wrong content type, etc.). |
| 401 Unauthorized | You need to be authenticated to access this
resource. |
| 403 Forbidden | The user is not authorized to access this
resource. |
| 404 Not found | The resource was not
found. |
| 429 Too many requests | You hit a rate
limit.
|
| 500 Internal server error | You broke our system. Not nice. Please
[contact us](https://ctechnology.io/contact). |
All responses (that return something at all) are wrapped into the following
structure.
It is a deliberate choice to not use header fields for the metadata sent
along, as using
some fields on a JSON object is (in our experience) more straightforward to
use, allows seamless reuse of
data structures for RT (e.g., WebSocket) communication and easy extension
and configuration
for various types of returned data (paginated lists, single objects, errors,
etc.):
```json
{
"status": 12345,
"type": "SUCCESS",
"api_version": "v2.2",
"data": [ ... ],
...
}
```
Other notes:
- Datetime fields are always of the form `YYYY-MM-DDThh:mm:ss.sssZ`, meaning
that *all*
datetimes returned and accepted *must* be in UTC.
- An exception to this rule are settings (e.g., for vehicle services) where
a time
frame is specified, for example every Tuesday from 14:00 to 16:00. In this case,
the weekday is specified as `monday`, `tuesday`, `wednesday`, `thursday`, `friday`,
`saturday` or `sunday`, and the time simply as `14:00` resp. `16:00`. It is generally
assumed that this is local time, i.e., using the time zone at which a vehicle under
consideration is located (e.g., a user's timezone).
- Within the specification, IDs are specified as `string`, yet most IDs
you'll encounter
are actually numbers. This is simply to allow future changes towards string-based
IDs (such as UUIDs). As such, you should not rely on any ID being numeric.
## Errors
Responses indicating errors (all non-`20X` responses) always are of the
following form:
```json
{
"id": 98765,
"status": 12345,
"type": "NO_PERMISSION_USER_VIEW_MAP",
"api_version": "v2.2",
"severity": "LOW",
"message": "No permission to the given object.",
"message_i18n": "Keine Zugriffsrechte auf das angeforderte Objekt."
"data": null,
}
```
Here, `id` describes an internal error ID, the `type` is a textual
representation
of the ID (that might be more generic), the `severity` can be used to
determine
the course of action, and the `message` is a human-readable representation
of the
error (if available, it will be translated to the primary language of the
requesting
in the `message_i18n` field).
## Pagination
As mentioned above, resource lists are *always* paginated as described
below, where
`num_results` indicates the total number of resources available, `offset`
the
offset from starting at the beginning of the collection, and `limit` the
number
of resources returned. You can request different offsets and limits using
the
`offset=` and `limit=` query parameters on any of these endpoints.
The `next` and `previous` fields are optional, but might provide quick ways
to
retrieve more data from the c.technology system.
```json
{
"status": 12345,
"type": "SUCCESS",
"api_version": "v2.2",
"data": [ ... ],
"num_results": 1500,
"offset": 300,
"limit": 100,
"next": "https://ctechnology.io/api/v1.1/...?limit=50&after=XYZ",
"previous": "https://ctechnology.io/api/v1.1/...?limit=50&before=XYZ"
}
```
## Filtering, sorting and structuring
Several endpoints can be filtered, or subsets of data can be selected. If
not
indicated otherwise, you can filter by using the query parameter `filter=`,
followed by an HTML-encoded filter string, select subsets of data by
specifying
`fields=`, followed by a comma-separated list of fields, and sort by using
`orderby=` followed by a single field. By default, fields are sorted by
`timestamp`, if available.
## Rate limiting
You can make up to 80 requests per user per minute (limit to be increased
in the future and on demand), after which you will start receiving
`429 Too many requests` responses.
Note that for most purposes, you will want to use the c.technology real-time
(RT) API or our webhooks which are not limited in terms rates and can
provide
most information in a push-based manner.
## More information and resources
You can find more information on [ctechnology.io](https://ctechnology.io) or
on our
[company GitHub organization](https://github.com/c-technology).
Do not hesitate to contact us in case you have any questions or things
remain unclear.
servers:
- url: https://ctechnology.io/api/v2.2/
description: Primary server with auto-balancing.
security: []
tags:
- name: Authentication
description: |
Everything concerned with the authentication of users, organizations,
and apps.
- name: User
description: |
Everything concerned with user and organization accounts.
- name: Vehicle
description: |
Everything concerned with base vehicle properties.
- name: Trip
description: |
Everything concerned with trips and vehicle movements.
- name: Notification
description: |
Everything concerned with notifications and alerts.
- name: Geo
description: |
Everything concerned with geographic properties and functionalities.
- name: Insight
description: |
Everything concerned with advanced analytics and insights gained
from vehicle data.
- name: Note
description: |
Everything concerned with notetaking functionalities, such as the
calendar, notebook, document upload, etc.
- name: Maintenance
description: |
Everything concerned the predictive / preventive maintenance of vehicles.
- name: Vehicle Communication
description: |
Everything concerned with the communication with vehicles.
- name: Chore
description: |
Everything concerned with basic tasks such as image or document
uploading, system administration, etc.
- name: Security
description: |
Everything concerned with the authorizations, permissions, access
roles, etc.
- name: Payment
description: |
Everything concerned with the services, subscriptions, payments, etc.
- name: Developer
description: >
Everything concerned with the developer API, such as the SMTP settings,
etc.
- name: OEM Custom
description: |
Everything concerned with the OEM customizations, such as the
custom vehicle uploads etc.
paths:
/trip:
get:
tags:
- Trip
summary: Get trips
description: >
Gets trips that a user has access to. The trips are always ordered by
their
ending timestamp, newest one first. Use a `limit` query parameter to
bound
the number of trips returned.
parameters:
- name: to
in: query
schema:
type: string
format: date-time
description: Up until when to get the trips.
- name: limit
in: query
schema:
type: number
description: The number of trips to return.
- name: scope
in: query
schema:
$ref: '#/components/schemas/VisibilityScope'
description: The scope, publicly shared trips or a user's private ones.
responses:
'200':
description: Successful retrieval of trips.
content:
application/json:
schema:
type: object
title: TripPaginated
required:
- header
- data
properties:
header:
$ref: '#/components/schemas/APIHeaderPaginated'
data:
type: array
items:
$ref: '#/components/schemas/Trip'
'401':
$ref: '#/components/responses/APIResponseUnauthorized'
'403':
$ref: '#/components/responses/APIResponseForbidden'
'500':
$ref: '#/components/responses/APIResponseInternalServerError'
security:
- ApiKeyAuth: []
components:
schemas:
VisibilityScope:
x-internal: true
type: string
description: |
The visibility scope of trips, actions, etc.
enum:
- PUBLIC
- PRIVATE
APIHeaderPaginated:
type: object
title: API Header Paginated
description: >
Default header sent along with multi-resource responses (lists of
resources).
required:
- num_results
properties:
api_version:
type: string
description: The API version that this response adheres to.
readOnly: true
status:
type: string
description: A status code identifying this response. Usually "SUCCESS".
readOnly: true
message:
type: string
description: A descriptive English message about this response. Usually empty.
readOnly: true
permission_via:
type: array
description: A descriptive English message about this response. Usually empty.
items:
type: object
required:
- permission
- via
properties:
permission:
type: string
description: The permission that granted access to this API endpoint.
via:
type: string
description: >
Either `me` if a user permission granted access, or
`organization` if this is a
transitive permission.
enum:
- me
- organization
organization_id:
type: string
description: >-
The organization that gave access to this user for the given
resource.
readOnly: true
num_results:
type: number
description: The total number of results.
readOnly: true
offset:
type: number
description: The pagination offset.
readOnly: true
limit:
type: number
description: The pagination limit.
readOnly: true
Trip:
type: object
title: Trip
description: |
A single trip performed by a vehicle.
required:
- id
- vehicle_id
- timestamp_start
- timestamp_end
- completed
- deleted
- valid
- validation_score
- name
- driver
- image_rect_url
- speed_max
- speed_avg
- distance_tot
- distance_tot_gps
- duration_tot
- duration_cruising
- battery_start_level_volt
- battery_end_level_volt
- visibility
- num_likes
properties:
id:
type: string
description: A unique identifier to identify this trip.
readOnly: true
vehicle_id:
type: string
description: The ID of the vehicle this trip belongs to.
readOnly: true
timestamp_start:
type: string
format: date-time
description: The date/time at which this trip started.
readOnly: true
timestamp_end:
type: string
format: date-time
description: The date/time at which this trip ended.
readOnly: true
timestamp_original_start:
type: string
format: date-time
description: >-
The original start date/time of this trip, before any trimming
(e.g., due to land filter).
readOnly: true
timestamp_original_end:
type: string
format: date-time
description: >-
The original end date/time of this trip, before any trimming (e.g.,
due to land filter).
readOnly: true
completed:
type: boolean
description: If this trip is completed or not.
readOnly: true
deleted:
type: boolean
description: If this trip was deleted (by a user).
valid:
type: boolean
description: >
If this trip is valid (based on the c.technology AI-based trip
assessment). Invalid
trips might appear due to GPS errors or missing GSM connections.
readOnly: true
validation_score:
type: number
description: >
A score in [0, 1] that describes the likelihood of this trip being
valid.
1 means we are 100% confident this is a real trip, 0 means we are
100% confident this is not a real trip, but GPS / sensor noise.
on_land:
type: boolean
description: If this trip is (partially) on land (for boats).
readOnly: true
name:
type: string
description: The (user-given) name of this trip.
driver:
type: string
description: The (user-given) driver name of this trip.
notes:
type: string
description: (User-added) notes of this trip. Formatted using Markdown.
fuel_manual_lt:
type: number
description: >-
The amount the vehicle was refueled on this trip, as manually set by
a user, in l (may be over 100%).
image_rect_url:
type: string
description: An URL pointing to a rectangular visualization of this trip.
readOnly: true
speed_max:
type: number
description: The maximal speed on this trip, in km/h.
readOnly: true
speed_avg:
type: number
description: The average speed on this trip (while driving), in km/h.
readOnly: true
distance_tot:
type: number
description: >-
The total distance of this trip using the best possible source, in
m.
readOnly: true
distance_tot_gps:
type: number
description: The total distance of this trip as measured by the GPS sensor, in m.
readOnly: true
distance_tot_can:
type: number
description: The total distance of this trip as given by the CAN bus, in m.
readOnly: true
distance_tot_odo:
type: number
description: The total distance of this trip, as measured by the odometer, in m.
readOnly: true
duration_tot:
type: number
description: The total duration of this trip, in s.
readOnly: true
duration_cruising:
type: number
description: The total duration spent cruising, in s.
readOnly: true
fuel_start_level_pct:
type: number
description: The fuel level at the start of the trip, in %.
readOnly: true
fuel_start_level_lt:
type: number
description: The fuel level at the start of the trip, in l.
readOnly: true
fuel_most_recent_pct:
type: number
description: >-
The most up-to-date fuel reading, in % (if the trip is not
completed).
readOnly: true
fuel_most_recent_vlt:
type: number
description: >-
The most up-to-date fuel reading, in V (if the trip is not
completed).
readOnly: true
fuel_used_pct:
type: number
description: The amount of fuel used, in % (may be over 100%).
readOnly: true
fuel_used_lt:
type: number
description: The amount of fuel used, in l.
readOnly: true
fuel_num_refueled:
type: number
description: The number of times the vehicle was refueled on this trip.
readOnly: true
fuel_refueled_pct:
type: number
description: >-
The amount the vehicle was refueled on this trip, in % (may be over
100%).
readOnly: true
fuel_refueled_lt:
type: number
description: >-
The amount the vehicle was refueled on this trip, in l (may be over
100%).
readOnly: true
fuel_avg_lt_per_100km:
type: number
description: The average fuel consumption per 100km on this trip.
readOnly: true
fuel_avg_pct_per_100km:
type: number
description: The average fuel consumption per 100km on this trip, in %.
readOnly: true
battery_start_level_volt:
type: number
description: The battery level at the start of the trip, in V.
readOnly: true
battery_end_level_volt:
type: number
description: The battery level at the end of the trip, in V.
readOnly: true
start_energy_available_ah:
type: number
description: The energy available at the start of the trip, in Ah.
readOnly: true
end_energy_available_ah:
type: number
description: The energy available at the end of the trip, in Ah.
readOnly: true
continuous_energy_consumption_ah:
type: number
description: The continuous energy consumption on this trip, in Ah.
readOnly: true
start_energy_available_wh:
type: number
description: The energy available at the start of the trip, in Wh.
readOnly: true
end_energy_available_wh:
type: number
description: The energy available at the end of the trip, in Wh.
readOnly: true
continuous_energy_consumption_wh:
type: number
description: The continuous energy consumption on this trip, in Wh.
readOnly: true
start_energy_available_pct:
type: number
description: The energy available at the start of the trip, in %.
readOnly: true
end_energy_available_pct:
type: number
description: The energy available at the end of the trip, in %.
readOnly: true
continuous_energy_consumption_pct:
type: number
description: The continuous energy consumption on this trip, in %.
readOnly: true
n2k_operation_hours_tot:
type: number
description: >-
The total operation hours according to the NMEA2000 bus, in s (for
NMEA2000-enabled vehicles).
readOnly: true
can_fuel_consumption_avg:
type: number
description: >-
The average fuel consumption as reported by the CAN bus, in l/h (for
CAN-enabled vehicles).
readOnly: true
can_fuel_consumption_max:
type: number
description: >-
The maximal fuel consumption as reported by the CAN bus, in l/h (for
CAN-enabled vehicles).
readOnly: true
can_fuel_consumption_tot:
type: number
description: >-
The total fuel consumption as reported by the CAN bus (for
CAN-enabled vehicles).
readOnly: true
can_rpm_max:
type: number
description: >-
The maximal motor rounds per minute (RPM) as reported by the CAN bus
(for CAN-enabled vehicles).
readOnly: true
can_rpm_avg:
type: number
description: >-
The average motor rounds per minute (RPM) as reported by the CAN bus
(for CAN-enabled vehicles).
readOnly: true
visibility:
$ref: '#/components/schemas/VisibilityScope'
description: >
The visibility of this trip, e.g., if it is shared with the public
or certain organizations,
or kept for the user him-/herself.
num_likes:
type: number
description: >
The number of likes this trip received from other people in the
c.technology cloud system, or
within an OEM / professional ecosystem.
readOnly: true
is_liked_by_me:
type: boolean
description: >
If the trip can be liked (is public or similar), this attribute is a
short-hand to know if the
currently logged in user him-/herself liked the trip.
APIError:
type: object
title: API Error
description: |
A generic response after any erroneous process (error of any kind). This
response contains fields to identify the particular error.
required:
- header
- error
properties:
header:
$ref: '#/components/schemas/APIHeaderSingle'
error:
type: object
description: |
Containing detailed information about the error.
properties:
id:
type: string
description: |
An internal ID given to this particular error instance.
This might not be available, as not all errors are uniquely
logged and given an id.
readOnly: true
status:
type: number
description: |
An error code that can be used to identify this error.
readOnly: true
type:
type: string
description: |
A more generic description of the error that can be
used to generate an error message for the user.
readOnly: true
severity:
type: string
description: |
An indication of how severe the error is. You might use this
to custom-tailor the response to the user.
readOnly: true
enum:
- ALERT
- HIGH
- MEDIUM
- LOW
message:
type: string
description: |
A human-readable English message that describes the error.
readOnly: true
message_i18n:
type: string
description: |
A human-readable message in the primary language of the
user that describes the error. Note that this might not
always be available.
readOnly: true
data:
type: object
title: Error Data
description: |
Additional data that might be added to this error.
readOnly: true
APIHeaderSingle:
type: object
title: API Header Single
description: |
Default header sent along with single-resource responses.
properties:
api_version:
type: string
description: >-
The API version that this response adheres to. Usually the same as
in the request URL.
readOnly: true
status:
type: string
description: A status code identifying this response. Usually "SUCCESS".
readOnly: true
message:
type: string
description: A descriptive English message about this response. Usually empty.
readOnly: true
permission_via:
type: array
description: A descriptive English message about this response. Usually empty.
items:
type: object
required:
- permission
- via
properties:
permission:
type: string
description: The permission that granted access to this API endpoint.
via:
type: string
description: >
Either `me` if a user permission granted access, or
`organization` if this is a
transitive permission.
enum:
- me
- organization
organization_id:
type: string
description: >-
The organization that gave access to this user for the given
resource.
readOnly: true
responses:
APIResponseUnauthorized:
description: |
You need to be authenticated to perform this action.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
APIResponseForbidden:
description: |
You have no permission to perform this action.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
APIResponseInternalServerError:
description: |
The server encountered an internal error.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
description: |
Note that the API key has to be sent as `Token 123` where `123` is
the key you received after logging in or by creating on the developer
dashboard.
name: Authorization
````