> ## 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 overall summary
> Returns the overall summary of the vehicle. This summarizes everything since
the vehicle / IoT device was put into service and adds some other interesting
information.
## OpenAPI
````yaml api-reference/openapi.yml get /vehicle/{vehicle_id}/summary/overall
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:
/vehicle/{vehicle_id}/summary/overall:
get:
tags:
- Insight
summary: Get overall summary
description: >
Returns the overall summary of the vehicle. This summarizes everything
since
the vehicle / IoT device was put into service and adds some other
interesting
information.
parameters:
- name: vehicle_id
in: path
schema:
type: string
required: true
description: ID of vehicle to retrieve the overall summary for.
responses:
'200':
description: |
Successful retrieval of this vehicle's overall summary.
content:
application/json:
schema:
type: object
title: VehicleSummaryOverallSingle
required:
- header
- data
properties:
header:
$ref: '#/components/schemas/APIHeaderSingle'
data:
$ref: '#/components/schemas/VehicleSummaryOverall'
'401':
$ref: '#/components/responses/APIResponseUnauthorized'
'403':
$ref: '#/components/responses/APIResponseForbidden'
'500':
$ref: '#/components/responses/APIResponseInternalServerError'
security:
- ApiKeyAuth: []
components:
schemas:
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
VehicleSummaryOverall:
type: object
title: Vehicle Summary Overall
description: |
A summary of a vehicle's activities over its complete lifetime.
required:
- vehicle_id
- timestamp_last_update
- timestamp_last_processed
- distance_tot
- distance_avg
- duration_tot
- duration_avg
- speed_max
- speed_avg
- battery_main_min
- battery_main_max
- num_trips
properties:
vehicle_id:
type: string
description: The ID of the vehicle for which this summary is.
readOnly: true
timestamp_last_update:
type: string
format: date-time
description: The timestamp of the last update received from the vehicle.
readOnly: true
timestamp_last_processed:
type: string
format: date-time
description: >
The timestamp this vehicle was last processed by the c.technology
cloud system.
This might not coincide with the last update, as vehicles are
continuously processed,
even when no new updates arrive at the system.
readOnly: true
distance_tot:
type: number
description: The total distance driven, in m.
readOnly: true
distance_avg:
type: number
description: The average distance per trip, in m.
readOnly: true
duration_tot:
type: number
description: The total duration driven, in s.
readOnly: true
duration_avg:
type: number
description: The average duration per trip, in s.
readOnly: true
speed_max:
type: number
description: The maximal speed, in km/h.
readOnly: true
speed_avg:
type: number
description: The average speed (when driving), in km/h.
readOnly: true
fuel_timestamp_last_refueled:
type: string
format: date-time
description: The timestamp when this vehicle was last refueled.
readOnly: true
fuel_num_refueled:
type: number
description: The number of refuel actions.
readOnly: true
fuel_used:
type: number
description: The total amount of fuel used, in l.
readOnly: true
fuel_timestamp_last_update:
type: number
description: >
The timestamp of the last fuel reading. Often, fuel sensors are
turned off when
the motor is not running or a main switch/the ignition is off.
readOnly: true
fuel_num_calibration_updates:
type: number
description: The number of updates that are used to calibrate the fuel sensor.
readOnly: true
battery_main_min:
type: number
description: The minimal battery state, in V.
readOnly: true
battery_main_max:
type: number
description: The maximal battery state, in V.
readOnly: true
num_trips:
type: number
description: The number of trips done by this vehicle.
readOnly: true
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
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
````