- Base Concepts
This API is a RESTful API implemented using Django/Python technologies, everything being based on HTTP.
A client for this service would perform a couple of simple HTTP requests to the server.
The default SafeFleet API server address is api.safefleet.eu, on TCP port 443 (HTTPS).
Requests
The base path that the requests are made to has the following format:
/safefleet/api/{version}/{endpoint}
where version is an optional part of the path indicating a specific API version to be used
and endpoint is one of the available endpoints.
For details on available API versions and how to use them see API Versions.
Values are transmitted in the request body and must be in JSON format.
Don't forget to set the request content type to application/json.
Responses
The actual response is given by the server in the body section. The format used is JSON, encoded using UTF-8 text and with a
content type of application/json.
In case of an error, the server returns a corresponding message. For example,
when an object cannot be found the response body looks like this:
{"message": "object not found: vehicle_id=128"},
having a status code of 404 Not Found (see status codes for more details).
Conventions
All dates are UTC and are transmitted (from and to the server) in ISO 8601 format:
- yyyy-mm-dd (e.g. 2011-05-13) for a simple date
- yyyy-mm-ddTHH:MM:SSZ (e.g. 2011-05-13T03:14:15Z) for a date with time
All countries are transmitted as ISO 3166-1 alpha-2 capital two-letter country codes (e.g. FR for France).
Phone numbers are always preceded by a + sign and must include the country prefix.
These are the conventional units used for the various values throughout the API:
- Distances and odometers are expressed in kilometers and are usually floating-point numbers.
- Speeds are all expressed in kilometers/hour.
- Durations are expressed in seconds.
- Azimuths are expressed in degrees, ranging from 0° to 359°.
- Latitudes and longitudes are expressed as decimal degrees, using the WGS84 system (e.g. 45.75232).
- Absolute fuel consumptions are expressed in liters.
- Fuel levels are expressed in percents.
- Average consumptions are expressed in liters/100 kilometers.
- Stationary consumptions are expressed in liters/hour.
Constraints
The number of requests per second is limited on a per company basis. The following constraints are imposed:
- the average number of requests per second must not exceed 0.5 (i.e. one request each two seconds)
- a burst of no more than 10 consecutive requests is allowed, provided that the overall average request rate stays within the boundaries
When any of these limits is exceeded, a 503 Service Unavailable status will be returned.
Status Codes
HTTP status codes are used to inform the client about the way the request was processed.
Any errors that have been encountered while processing the request are signaled using these codes, as follows:
- 200 OK indicates a successfully processed request; the response contains the requested content
- 201 Created indicates a successfully processed creation request; the response contains the created object
- 204 No Content indicates a successfully processed request; the response has no content
- 400 Bad Request indicates a problem with the request parameters; here are some common error messages:
- {"message": "missing parameter: ..." - an expected parameter was not supplied
- {"message": "invalid parameter value: ..."} - a parameter was supplied with an invalid value
- {"message": "invalid parameters: ..."} - more parameter values together are not valid
- 403 Forbidden indicates one of the following:
- the request is not authenticated (see authentication), while the error message says {"message": "authentication required"}
- the authentication request failed, while the error message says {"message": "authentication failed"}
- the authentication process requires 2FA code to complete, when the error message says {"message": "2fa code required"}
- the requested endpoint/resource is forbidden to the currently authenticated user, while the error message says {"message": "forbidden"}
- 404 Not Found is accompanied by an error message and indicates one of the following:
- {"message": "object not found: ..."} - one of the requested objects wasn't found on the server
- {"message": "function not found: ..."} - the called endpoint/function does not exist
- 500 Server Error tells that an error occurred on the server side while processing the request
- 502 Bad Gateway indicates that one of the backend services is currently unavailable
- 503 Service Unavailable indicates that the request rate is too high (above the imposed limits)
- 504 Gateway Timeout indicates that our servers are currently overloaded
API Versions
In order to be able to improve the API while preserving backwards compatibility with existing clients, the SafeFleet API interface
allows specifying a desired version in the URI.
A complete version string has the following format: vX.Y (e.g. v1.1), where X is the major version
and Y is the minor version. The current major version is 2. We only plan to change the major version when
we redesign major parts of the API.
Minor versions, however, change more often. Whenever we update the parameters or the response format of an endpoint,
or whenever we rename or remove an endpoint, we'll update the minor version.
This being said, if you want to always use the latest version and you're prepared to quickly adapt your code to our changes, just don't specify any version at all, e.g.:
/safefleet/api/{endpoint}
If you want to use the latest minor version of a specific major version, specify only the major version, e.g.:
/safefleet/api/v2/{endpoint}
If you want to use a precise version because you don't plan to update your API client code too often, specify it entirely, e.g.:
/safefleet/api/v2.0/{endpoint}
- Authentication
Three different authentication methods are accepted by the API.
Choosing one or another depends strictly on the purpose of the API client.
It is important to note that both of these authentication methods require an existent user in the system,
and that the user can be configured to work with only one method, not with both.
Session-based Authentication
This is the most commonly used method and requires a pair of username and password values to be sent to the server
once, at the beginning of the session. The user is identified by its unique username.
The mechanism is based on a session id transmitted through an HTTP cookie named sessionid.
More precisely, the server maintains a session for an authenticated user for a couple of days.
If this session has expired, or just doesn't exist yet, the server will respond with a 403 Forbidden
to any regular request, with an error message saying {"message": "authentication required"}.
To open a new session, a call to a special authenticate endpoint must be requested.
This endpoint takes the username and the password as parameters. The request must use the POST method.
In case of successful authentication, the server responds with 200 OK and the content {"message": "ok"}.
In case of unsuccessful authentication, 403 Forbidden is returned and the error message is {"message": "authentication failed"}.
Upon successful authentication, the server normally responds directly with the content {"message": "ok"},
and offers the client the session id in a cookie. This session id must be included as a cookie with any further requests.
If however, the user resides on a different server, the URL of this server is returned,
and the client is required to change its base URL accordingly.
This "soft" redirect actually indicates that the user, together with the whole customer data reside on a different server (also called instance),
and points the API client to that instance's URL. Here's an example of such an answer:
{"url": "http://instance13.safefleet.eu/safefleet/api"}
The redirect was implemented to allow starting with a single common URL as an entry point for anyone using the SafeFleet API,
regardless of the server on which the user is stored. The API client should be written in such a way that it is aware of this case.
Note: once you found out your final URL, you can use it directly from the beginning of your authentication flow, thus avoiding the extra "soft" redirect step.
For users with 2FA enabled, an additional authentication step is necessary to send the 2FA code. After the first authentication call on the final
instance, 403 Forbidden is returned with the content set to {"message": "2fa code required"}. In this case, the client must re-issue
the authentication request, including the 2FA code (along with username and password).
Client ID-based Authentication
This authentication mechanism should be used when there is only one user that the API client works with,
and this user never changes. The user is in fact associated to the API client and thus uniquely
identifies the client on the server. Hence the parameter called client_id which is used instead of a username or a
sessionid.
Moreover, there is no session and the authentication information has to be transmitted with every request.
This is not a security issue thanks to the use of a signature which is based on a shared secret and
the timestamp of the request. The secret is never transmitted between the server and the client.
The signature is computed using the following formula:
signature = sha1(secret + timestamp),
where the secret and the timestamp (in seconds since Epoch) are concatenated as strings,
and the signature itself is expressed as string, in lowercase hex digits.
Now the following three parameters have to be sent with each request, in addition to the
parameters that are normally required by the endpoint:
- client_id - the client id that links the user on the server to the client
- signature - as described above
- timestamp - the current timestamp, the one used to compute the signature
A time skew of at most ±5 minutes is accepted between the client and the server's timestamps.
JWT-based Authentication
To use JWT Authentication the user must obtain two tokens, one access token and one refresh token.
This is done by sending a POST request to the /authenticate/jwt/login endpoint.
The request must have in the body a json with the keys (and the correct values) "username" and "password".
Optional, for testing purposes, the json can also have the key(s) "access_token_seconds_duration" and/or "refresh_token_seconds_duration".
Those keys will specify the duration of each token, but the duration must be shorter than the default duration.
If the credentials are valid, the user will get a response with a json with the keys "access_token", "refresh_token" and "message" (value of the message will be "ok")
If the credentials are invalid or something is missing/wrong, the response will have ony the "message" key, explaining what went wrong.
After this, assuming that the credentials were valid, the user is authenticated and will need to use the tokens for any request.
Each request needs to have in headers the key "Authorization" and the value of the key set to "Bearer access_token" (where access_token is the value of the access token)
Because the access token is short lived, after a while a request will fail with the response {"message": "authentication required"}.
When this happens, a new request must be used to the endpoint /authenticate/jwt/refresh_token
The body of this request should have a json with the keys (and values) "access_token", "refresh_token".
Similar to the login endpoint, for testing purposes, the json can also have the key(s) "access_token_seconds_duration" and/or "refresh_token_seconds_duration".
Those keys are optional and they will specify the duration of each token, but the duration must be shorter than the default duration.
The response (assuming that everything is correct) will be a json with a new set of tokens (access and refresh) and the message "ok".
If the access token is not expired the endpoint the "new" set will be identical to the set provided in the json, but this should occur only when the endpoint is not used from frontend, in "real life" the end user should never be in this situation.
If there's a problem, the response will have only the "message" key (explaining, hopefully, the problem).
If the user wants to invalidate the tokens he needs to logout, by sending a request to the enpoint /authenticate/jwt/logout.
Similar to all the requests (except login), the body of the request will need to contain the access and refresh tokens.
If they are correct, the server will return status 204 (no content), otherwise a message with what went wrong.
- SafeFleet Objects
The information maintained by the SafeFleet system is structured in a hierarchy of objects, as shown in the following figure:
The SafeFleet objects and their relationsInstances
An instance represents in fact a server that runs our SafeFleet application stack.
The architecture of the system is divided into multiple instances to facilitate scaling and to
accommodate the different types and sizes of customers.
Customer's data is stored entirely on one single instance (that is, not scattered across multiple servers).
The developer using this API must take this into account and not hardcode the base URL (or IP address for that matter)
of a certain instance, but rather use the authenticate method on the single common entry point
https://api.safefleet.eu and follow the "soft" redirects, as described in authentication.
Companies
Companies are objects that group all the information of a SafeFleet customer. A company has the following fields:
- company_id - a unique id given to each company by the system
- name - a name given to the company
- address - the address, composed of
- country
- county
- city
- street
- number
- postal_code
- phone
- email
- vat_number - the VAT (tax) number of the company
- type - the type of company (see company types)
- activity_type - the type of activity (see activity types)
- login_allowed - general access restriction flag
- web_access - web access restriction flag
- api_access - API access restriction flag
- agent_id - optional agent user id
Fleets
A fleet represents a subdivision (a department) of a company. Two types of fleets are distinguished:
- root fleets - the ones that are subordinated directly to the company (usually only one, having the name of the company)
- subfleets - all the fleets that are subordinated to another fleet
A fleet has the following fields:
- fleet_id - a unique id given to each fleet by the system
- name - a name given to the fleet
- lat - the latitude of the fleet headquarters
- lng - the longitude of the fleet headquarters
- address - the address, composed of
- country
- county
- city
- street
- number
- postal_code
- phone
- email
Vehicles
Vehicles are probably the most important pieces of the SafeFleet system.
Vehicles make journeys delimited by a start point and a stop point.
They send so-called presences to the server. These presences include the position,
the speed and the azimuth of the vehicle at specific moments, and are used to reconstruct the trajectory.
Vehicles generate events that are stored on the server and can be used to tell the behaviour of the driver,
to identify problems with the vehicle's device or to simply keep an eye on the vehicle.
Vehicles can also generate contact records whenever one of their configured digital inputs (such as door contacts) change state.
Vehicles equipped with temperature sensors generate temperature records.
Each vehicle has a list of attributes (such as engine displacement or insurance expiry date).
Fuelings can be imported into our system and associated to their corresponding vehicles.
Vehicles can have associated documents that usually correspond to a period of activity (such as journeys).
Tickets are used to keep track of various issues regarding each vehicle.
All these are shown in the following diagram:
Objects related to a vehicle- vehicle_id - a unique id given to each vehicle by the system
- name - a name given to the vehicle
- license_plate - the license plate of the vehicle
- vin - the vehicle identification number
- maker - the maker of the vehicle
- model - the model of the vehicle
- type - the type of the vehicle (see vehicle types)
- year_of_manufacture - the year when the vehicle was manufactured
- identification_card - the identification card number of the vehicle
- working_schedule - the working schedule of the vehicle (intervals of time for each day of the week)
- default_driver - the name of the vehicle’s default driver
- default_driver_phone - the phone number of the vehicle’s default driver
- tracked - a boolean indicating whether the vehicle is tracked (using a GPS device) or not
Apart from these static fields, each vehicle has the following fields that change often, called the current information:
- lat - the current latitude of the vehicle
- lng - the current longitude of the vehicle
- moment - the moment of the last reported presence
- last_sync - the moment of the last received message (which can be newer than the last reported presence moment)
- speed - the current speed of the vehicle
- azimuth - the current azimuth of the vehicle
- status - the current status of the vehicle (see vehicle statuses)
- engine_since - the moment of the last engine on/off event
- navig_state - the current navigation state of the vehicle (see navigation vehicle states)
- driver_id - the id of the driver currently driving the vehicle (if any)
- satellites - the current number of visible GNSS satellites
- pdop - the current GNSS PDOP parameter
- total_fuel_used - the total fuel consumed so far, in liters (if available)
- fuel_level - the current fuel level, as percent (if available)
- battery_soc - the current battery state of charge, as percent (if available, for electric vehicles)
- vrob - the available range on battery, in kilometers
- charging_cable_connected - whether the charging cable is currently connected or not
- battery_charging - whether the battery is currently charging or not
- purpose - the current journey purpose (usually `b` for business or `p` for private)
- journey_code - the current journey code
- contacts - a dictionary with current contact values (see contacts)
- temperatures - a dictionary with current temperature values (see temperatures)
Users
Each user has one of the five defined levels of access:
- Site Administrator - has full rights over the entire SafeFleet system and can perform maintenance tasks
- SafeFleet Administrator - has full rights over all the companies
- Company Administrator - has full rights over his company (including all fleets and subfleets)
- Department Administrator - has full rights over his fleet and all the subfleets below
- Department Member - has limited rights over his fleet and all the subfleets below
Users can receive notifications when vehicles generate events or when
attributes of type date expire.
A user has the following fields:
- user_id - a unique id given to each user by the system
- username - the username used for login
- first_name - user's first name
- last_name - user's last name
- email - the email of the user
- phone - the phone number of the user
- timezone - the name of the user's timezone preference
- timezone_offset - the timezone offset relative to UTC, in minutes
- units - user's units preference (see unit preferences)
- has_2fa - whether 2FA is enabled or not for this user
- profile_photo - profile photo (full URL/data URI)
- level - the level of access (see user levels)
Users have a set of notification preferences that control the various notifications they receive.
Drivers
Drivers are authenticated by the system using special keys individually assigned to each driver.
A vehicle can be driven by only one driver at a certain moment. However it can have a secondary driver, waiting to take
over the wheel.
A driver has the following fields:
- driver_id - a unique id given to each driver by the system
- name - the full name of the driver
- email - the email of the driver
- phone - the phone of the driver
- personal_identification - a personal identification code for this driver
- key_code - the unique code of the driver's assigned key
- driver_code - a unique code associated to the driver
- active - whether the driver is still active or not
- fcm_id - Firebase Cloud Messaging identifier
Each driver has a list of attributes used to store additional data.
Apart from these static fields, a driver may expose details about the tachograph information, in a field
called tacho:
- state - the current tachograph driver state (see tacho states)
- time_driven_since_short_break - the number of seconds elapsed since last short break
- time_driven_since_long_rest - the number of seconds elapsed since last long rest
- leave_in - time, in seconds, after which driver may start driving
- next_short_break_in - time, in seconds, after which driver should take a short break
- next_long_rest_in - time, in seconds, after which driver should rest
Driver Groups
Drivers are grouped into driver droups. A driver can belong to zero, one or multiple groups.
A driver group has the following fields:
- driver_group_id - a unique id given to each driver group by the system
- driver_ids - the list of ids of the drivers belonging to the group
- name - the group name
Points Of Interest
Each fleet has points of interest (POIs). A POI is a pair of (latitude, longitude) with a certain tolerance (delta) around this central point.
POIs are in fact small rectangles used to easily identify and name places on map.
A POI has the following fields:
- poi_id - a unique id given to each POI by the system
- name - the name given to the POI
- category - the category of the POI
- comment - an optional comment for the POI
- business - a flag that indicates whether the POI is a business destination or not
- visible_upwards - a flag indicating that the POI is visible in the parent fleets
- visible_downwards - a flag indicating that the POI is visible in the subfleets
- lat - the the latitude of the central point
- lng - the the longitude of the central point
- delta_lat - the latitude tolerance
- delta_lng - the longitude tolerance
- address - the address, composed of
- country
- county
- city
- street
- number
- postal_code
- phone
- email
Regions Of Interest
Each fleet has regions of interest (ROIs). A ROI is a collection of pairs of (latitude, longitude).
ROIs are in fact polygons which define a geographical area. They are used for area-related reports and geofence notifications.
A ROI has the following fields:
- roi_id - a unique id given to each ROI by the system
- name - the name given to the ROI
- category - the category of the ROI
- visible_upwards - a flag indicating that the ROI is visible in the parent fleets
- visible_downwards - a flag indicating that the ROI is visible in the subfleets
- polygon - a list of points composed of
- lat - the latitude of the point
- lng - the longitude of the point
Tracks
Tracks are used to compare the actual trajectory of a vehicle with an imposed one. A track is basically a set of successive points.
The points that make up a track can be points of interest as well as way points (arbitrary points).
A track has the following fields:
- track_id - a unique id given to each track by the system
- name - the name given to the track
- geofence - a flag indicating whether the track is used as a geofence or not
- visible_upwards - a flag indicating that the track is visible in the parent fleets
- visible_downwards - a flag indicating that the track is visible in the subfleets
- pois - a list of POIs, composed of
- poi_id - the id of the POI
- order - the order of the POI in the track
- lat - the latitude of the POI
- lng - the longitude of the POI
- way_points - a list of points composed of
- order - the order of the way point in the track
- lat - the latitude of the point
- lng - the longitude of the point
Navigation Jobs
A navigation job is basically a task given to the driver to be used on the navigation device attached to the vehicle.
The destination of a job can be either a random address or a point of interest.
Jobs are managed using state machines. For more information on the available states see navigation job states
and navigation vehicle states.
A navigation job has the following fields:
- navig_job_id - a unique id given to each navigation job by the system
- name - the name given to the job's destination
- message - the message as seen by the driver
- remark - a remark message associated to the job (usually the result of the job)
- lat - the latitude of the destination of the job
- lng - the longitude of the destination of the job
- vehicle_id - the id of the vehicle to which this job is assigned (if any)
- created - the moment when the job was created (added to the system)
- start - the moment when the job is to be started
- due - the moment when the job is due
- state - the current state of the job (see navigation job states)
- poi_id - the id of a point of interest, when the job's destination is a point of interest
- address - the address, composed of
- country
- county
- city
- street
- number
- postal_code
- phone
- email
Carpool Reservations
A carpool reservation represents the act of booking a certain vehicle by a certain user for a given period of time.
Carpool reservations may not overlap but can be cancelled. A log of all the reservations made (or cancelled) for each vehicle is kept by the system.
A carpool reservation has the following fields:
- carpool_reservation_id - a unique id given to each carpool reservation by the system
- vehicle_id - the id of the vehicle that was booked with this reservation
- user_id - the id of the user who made the reservation
- created - the moment when the reservation was made
- start - the beginning of the reservation period
- stop - the end of the reservation period
- cancelled - whether the reservation was cancelled or not
- remark - an optional, free-form text attached to the reservation
Presences
Presences represent the positions and all the information that is sampled, recorded and transmitted by a vehicle in time.
Presences are used to recreate the trajectory of a vehicle in a specified interval of time.
A presence has the following fields:
- vehicle_id - the id of the vehicle that reported the presence
- moment - the moment when the presence was generated
- lat - the latitude of the vehicle at that moment
- lng - the longitude of the vehicle at that moment
- speed - the vehicle speed at that moment
- azimuth - the azimuth of the vehicle at that moment
Journeys
A journey is delimited by the moment when the engine starts and the moment when it stops.
A journey has the following fields:
- vehicle_id - the id of the vehicle that made the journey
- journey_id - the id of the journey record
- start - an object with:
- moment - the moment when the journey began
- lat - the latitude of the starting point
- lng - the longitude of the starting point
- stop - an object with:
- moment - the moment when the journey ended
- lat - the latitude of the stop point
- lng - the longitude of the stop point
- distance - the total distance travelled during the journey
- idle_duration - the total idling time during the journey
- consumption - an object with:
- value - the quantity of the fuel consumed
- measured - a boolean indicating whether the value was measured or computed
- max_speed - the maximum speed reached during the journey
- driver_id - the id of the driver that made the journey
- purpose - the journey purpose (usually `b` for business or `p` for private)
- journey_code - an optional user-defined journey code
Events
Events are generated by vehicles and represent important facts that occurred during journeys (or outside journeys, for that matter).
Events are used to tell the behaviour of the drivers, to identify problems with the vehicle's device or to simply keep an eye on the vehicle.
An event has the following fields:
- vehicle_id - the id of the vehicle that generated the event
- event_id - the id of the event record
- moment - the moment when the event was generated
- type - the type of the event (see event types)
- lat - the latitude where the event was generated
- lng - the longitude where the event was generated
- driver_id - the id of the driver that was driving the vehicle when the event was generated
- track_id - the id of the track, in case of a geofence event related to a track
- roi_id - the id of the ROI, in case of a geofence event related to a ROI
Contacts
Contact records are generated by vehicles when the state of one of their configured digital inputs changes.
Each input has an identifier that helps associating it with a certain function (such as a door contact).
There is a list of predefined input ids, but the actual id of the input may have any other integer value.
A contact record has the following fields:
- vehicle_id - the id of the vehicle that generated the contact record
- contact_id - the id of the contact record
- moment - the moment when the record was generated
- input_id - the id of the input that generated the contact record (see input ids)
- input_value - the new value of the input (normally either 0 or 1)
- lat - the latitude where the record was generated
- lng - the longitude where the record was generated
Temperatures
Temperature records are generated by vehicles equipped with temperature sensors.
Up to 4 temperature sensors can be attached to each vehicle.
A temperature record has the following fields:
- vehicle_id - the id of the vehicle that generated the temperature record
- temperature_id - the id of the temperature record
- moment - the moment when the record was generated
- temp - the value of the first temperature sensor, in degrees Celsius
- temp2 - the value of the second temperature sensor, in degrees Celsius
- temp3 - the value of the third temperature sensor, in degrees Celsius
- temp4 - the value of the fourth temperature sensor, in degrees Celsius
- lat - the latitude where the record was generated
- lng - the longitude where the record was generated
Attributes
Attributes store additional information about vehicles and other objects, such as technical specifications or insurance expiry dates.
Custom attributes can be defined by the user, aside from the common ones that are available by default.
An attribute has the following fields:
- vehicle_id - the id of the vehicle to which the attribute belongs (only for vehicle attributes)
- driver_id - the id of the driver to which the attribute belongs (only for driver attributes)
- name - the name of the attribute
- slug - a simplified name, containing only alphanumeric chars and underscores
- type - the type of the attribute (see attribute types)
- value - the value of the attribute
Fuelings
A fueling has the following fields:
- vehicle_id - the id of the vehicle that was fuelled
- moment - the moment of the fueling
- quantity - the fuelled quantity
- price - the total price of the fueling
- type - the type of the fuel (see fuel types)
- provider - the name of the fuel provider
- odometer - the vehicle odometer at the moment of the fueling
- station - the name of the fuel station
- card - the card number used for the fueling payment
- remark - an optional remark for the fueling
Documents
A document has the following fields:
- vehicle_id - the id of the vehicle to which the document belongs
- moment - the moment when the document was uploaded
- name - the document name
- content_type - the content type of the document
- content - base64-encoded content
Tickets
A ticket has the following fields:
- vehicle_id - the id of the corresponding vehicle
- opened_moment - the moment when the ticket was opened
- reporter_id - the id of the reporter user
- responsible_id - the id of the user that is responsible of the ticket
- issue - the description of the ticket's issue
- remark - an optional internal textual remark
- status - the current status of the ticket (see ticket statuses)
Temporary Links
A temporary link has the following fields:
- vehicle_id - the id of the corresponding vehicle
- link - the public URL of the temporary link
- expiry_moment - the moment after which the link expires
- trajectory_days - the number of days of trajectory that are displayed when visiting the link
- message - an optional message to show in the link page
- Available Endpoints
Function parameters whose names are written in italics are optional.
Parameters that are separated by a pipe character "|" are mutually exclusive.
The returned values are documented for the successful case, when the status is 200 OK.
Whenever an error occurs, the response is as documented in status codes.
|
POST
| /authenticate |
| This function is used to authenticate the client with the server and obtain the sessionid.
The supplied username must exist on the server. |
| username | String |
| the login username |
| password | String |
| the login password |
| code | String |
| the 2FA code |
| note | additional fields may be returned in the response |
| returns | ‣ the message "ok", if the user resides on this instance |
| {"message": String} |
| ‣ the error message "2fa code required" if 2FA is enabled and code is to be sent |
| {
"message": String,
"phone_hint": String
} |
| ‣ the instance's URL, if the user resides on another instance |
| {"url": String} |
|
POST
| /authenticate_vehicle |
| This function is similar to authenticate but intended for vehicles rather than users.
It can be used instead of authenticate if a vehicle's PIN and license plate are known,
to perform API requests on vehicle's behalf.
Driver PIN can and should be used instead of vehicle PIN, if driver phone is supplied. |
| license_plate | String |
| vehicle's license plate (any format is fine) |
| pin | String |
| vehicle PIN |
| driver_phone | driver's phone (may be required, depending on company setting) |
| returns | ‣ the vehicle details, if the vehicle resides on this instance; driver details are also returned
if driver_phone is supplied and a corresponding driver is found |
| {
"vehicle": {
"vehicle_id": Number,
"name": String,
"license_plate": String,
"vin": String,
"maker": String,
"model": String,
"year_of_manufacture": Number,
"identification_card": String,
"type": Number,
"default_driver": String,
"default_driver_phone": String,
"tracked": Boolean
},
"driver": {
"driver_id": Number,
"name": String,
"email": String,
"phone": String,
"personal_identification": String,
"key_code": String,
"driver_code": String,
"active": Boolean
}
} |
| ‣ the vehicle instance URL, if the vehicle resides on another instance |
| {"url": String} |
|
POST
| /authenticate_driver |
| This function is similar to authenticate but intended for drivers rather than users.
It can be used instead of authenticate if a driver's PIN and phone number are known,
to perform API requests on driver's behalf. |
| phone | String |
| driver's phone number |
| pin | String |
| driver's PIN |
| returns | ‣ the driver details, if the driver resides on this instance |
| {
"driver": {
"driver_id": Number,
"name": String,
"email": String,
"phone": String,
"personal_identification": String,
"key_code": String,
"driver_code": String,
"active": Boolean
}
} |
| ‣ the driver instance URL, if the driver resides on another instance |
| {"url": String} |
|
POST
| authenticate/jwt/vehicle/refresh_token |
| This function is used to obtain a new access token for jwt vehicle authentication, after the old one expires |
| access_token | String |
| old access token |
| refresh_token | String |
| the current refresh token |
| access_token_seconds_duration | access token duration in seconds, for frontend testing |
| acces_token_seconds_duration | Number |
| refresh_token_seconds_duration | Number |
| refresh token duration in seconds, for frontend testing |
| returns | ‣ the message "ok", and a new set of tokens (access and refresh) if the refresh token is valid |
| {
"message": "ok",
"access_token": String,
"refresh_token": String
} |
| ‣ a message explaining what went wrong if a param is missing or incorrect |
| {
"message": String
} |
|
POST
| authenticate/jwt/driver/refresh_token |
| This function is used to obtain a new access token for jwt driver authentication, after the old one expires |
| access_token | String |
| old access token |
| refresh_token | String |
| the current refresh token |
| access_token_seconds_duration | access token duration in seconds, for frontend testing |
| acces_token_seconds_duration | Number |
| refresh_token_seconds_duration | Number |
| refresh token duration in seconds, for frontend testing |
| returns | ‣ the message "ok", and a new set of tokens (access and refresh) if the refresh token is valid |
| {
"message": "ok",
"access_token": String,
"refresh_token": String
} |
| ‣ a message explaining what went wrong if a param is missing or incorrect |
| {
"message": String
} |
|
POST
| /authenticate/jwt/vehicle |
| This function is almost identical to authenticate_vehicle but it will give a pair of JWTs,
an access token and a refresh token instead of a session id.
It can be used instead of authenticate if a vehicle's PIN and license plate are known,
to perform API requests on vehicle's behalf.
Driver PIN can and should be used instead of vehicle PIN, if driver phone is supplied. |
| license_plate | String |
| vehicle's license plate (any format is fine) |
| pin | String |
| vehicle PIN |
| driver_phone | driver's phone (may be required, depending on company setting) |
| returns | ‣ an access token and a refresh token, the vehicle details, if the vehicle resides on this instance;
driver details are also returned if driver_phone is supplied and a corresponding driver is found |
| {
"message": ok,
"access_token": String,
"refresh_token": String,
"vehicle": {
"vehicle_id": Number,
"name": String,
"license_plate": String,
"vin": String,
"maker": String,
"model": String,
"year_of_manufacture": Number,
"identification_card": String,
"type": Number,
"default_driver": String,
"default_driver_phone": String,
"tracked": Boolean
},
"driver": {
"driver_id": Number,
"name": String,
"email": String,
"phone": String,
"personal_identification": String,
"key_code": String,
"driver_code": String,
"active": Boolean
}
} |
| ‣ the vehicle instance URL, if the vehicle resides on another instance |
| {"url": String} |
|
POST
| /authenticate/jwt/logout |
| This function is used to revoke (invalidate) the current set of tokens (access and refresh) |
| access_token | String |
| the access token |
| refresh_token | String |
| the refresh token |
| returns | ‣ no content, status 204, if the access and refresh tokens are correct |
| None |
| ‣ a message explaining what went wrong if a param is missing or incorrect |
| {
"message": String
} |
|
POST
| /authenticate/jwt/driver |
| This function is almost identical to authenticate_driver but it will give a pair of JWTs,
an access token and a refresh token instead of a session id.
It can be used instead of authenticate if a driver's PIN and phone number are known,
to perform API requests on driver's behalf. |
| phone | String |
| driver's phone number |
| pin | String |
| driver's PIN |
| returns | ‣ the driver details, if the driver resides on this instance |
| {
"driver": {
"driver_id": Number,
"name": String,
"email": String,
"phone": String,
"personal_identification": String,
"key_code": String,
"driver_code": String,
"active": Boolean
}
} |
| ‣ the driver instance URL, if the driver resides on another instance |
| {"url": String} |
|
POST
| /authenticate/jwt/refresh_token |
| This function is used to obtain a new access token, after the old one expires |
| access_token | String |
| old access token |
| refresh_token | String |
| the current refresh token |
| access_token_seconds_duration | access token duration in seconds, for frontend testing |
| acces_token_seconds_duration | Number |
| refresh_token_seconds_duration | Number |
| refresh token duration in seconds, for frontend testing |
| returns | ‣ the message "ok", and a new set of tokens (access and refresh) if the refresh token is valid |
| {
"message": "ok",
"access_token": String,
"refresh_token": String
} |
| ‣ a message explaining what went wrong if a param is missing or incorrect |
| {
"message": String
} |
|
POST
| /authenticate/jwt/login |
| This function is used to authenticate the client with the server and obtain the access token and the refresh token. |
| username | String |
| the login username |
| password | String |
| the login password |
| access_token_seconds_duration | access token duration in seconds, for frontend testing |
| acces_token_seconds_duration | Number |
| refresh_token_seconds_duration | Number |
| refresh token duration in seconds, for frontend testing |
| returns | ‣ the message "ok", and the tokens (access and refresh) if the credentials provided (username and password) are correct |
| {
"message": "ok",
"access_token": String,
"refresh_token": String
} |
| ‣ a message explaining what went wrong if a param is missing or incorrect |
| {
"message": String
} |
|
GET
| /companies |
| This function returns a list of all the companies present on the current instance. |
| see | companies |
| requires | at least SafeFleet administrator user level |
| returns | the list of companies |
| [
{
"company_id": Number,
"name": String,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
},
"vat_number": String,
"type": String,
"activity_type": String,
"login_allowed": Boolean,
"web_access": Boolean,
"api_access": Boolean,
"agent_id": Number
},
...
] |
|
POST
| /companies |
| This function adds a new company. It also creates a root fleet for the new company. |
| name | String |
| lat | Number |
| lng | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}, |
| vat_number | String |
| type | String |
| activity_type | String |
| login_allowed | Boolean |
| web_access | Boolean |
| api_access | Boolean |
| agent_id | Number |
| see | companies, fleets |
| requires | at least SafeFleet administrator user level |
| returns | the ids of the new company and root fleet |
| {"company_id": Number, "fleet_id": Number} |
|
GET
| /companies/{company_id} |
| This function returns detailed information about a company. |
| company_id | the id of the desired company, or "mine" for the current user's company |
| see | companies |
| requires | at least company administrator user level |
| returns | {
"company_id": Number,
"name": String,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
},
"vat_number": String,
"type": String,
"activity_type": String,
"login_allowed": Boolean,
"web_access": Boolean,
"api_access": Boolean,
"agent_id": Number
} |
|
PATCH
| /companies/{company_id} |
| This function updates the information of a company.
Only safefleet administrators
are allowed to update other companies. |
| company_id | the id of the desired company, or "mine" for the current user's company |
| name | String |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| vat_number | String |
| type | String |
| activity_type | String |
| login_allowed | Boolean |
| web_access | Boolean |
| api_access | Boolean |
| agent_id | Number |
| see | companies |
| requires | at least company administrator user level |
|
DELETE
| /companies/{company_id} |
| This function deletes a company. |
| company_id | the id of the desired company |
| see | companies |
| requires | at least SafeFleet administrator user level |
| note | this function recursively and permanently deletes all the objects related to this company |
|
GET
| /companies/{company_id}/functionalities |
| This function returns all the functionalities of a company, along with their current status. |
| company_id | the id of the desired company |
| see | companies |
| requires | at least SafeFleet administrator user level |
| returns | the list of functionalities |
| {
"flavour": String,
"func1": {
"title": String,
"category": String,
"choices": [
{
"name": String,
"value": any
},
...
],
"value": any
},
...
} |
|
PATCH
| /companies/{company_id}/functionalities |
| This function modifies the functionalities of a company. |
| company_id | the id of the desired company |
| flavour | String |
| the name of the flavour to use as functionality preset |
| func1... | any |
| the name of a functionality to be changed |
| see | companies |
| requires | at least SafeFleet administrator user level |
| note | ‣ more functionalities can be modified with one request, by specifying them as parameters |
| ‣ specifying a flavour as well as separate functionalities will result in a set of functionalities defaulting to the flavour but updated with supplied functionalities |
|
GET
| /companies/{company_id}/structure |
| This function returns the hierarchical structure of a company.
Optionally, vehicles, users and other related objects can be included in the result. |
| company_id | the id of the desired company, or "mine" for the current user's company |
| include_vehicles | set this to true to include vehicle ids in the result |
| include_users | set this to true to include user ids in the result |
| include_drivers | set this to true to include driver ids in the result |
| include_pois | set this to true to include point of interest ids in the result |
| include_rois | set this to true to include region of interest ids in the result |
| include_tracks | set this to true to include track ids in the result |
| see | companies |
| requires | at least company administrator user level |
| returns | the hierarchical structure of the company |
| {
"company_id": Number,
"name": String,
"fleets": [
{
"fleet_id": Number,
"name": String,
"fleets": [...],
"vehicle_ids": [Number],
"user_ids": [Number],
"driver_ids": [Number],
"poi_ids": [Number],
"roi_ids": [Number],
"track_ids": [Number]
},
...
]
} |
|
GET
| /companies/{company_id}/fleets |
| This function returns a list of the root fleets corresponding to a given company. |
| company_id | the id of the desired company, or "mine" for the current user's company |
| see | fleets |
| requires | at least department administrator user level |
| returns | the list of fleets |
| [
{
"fleet_id": Number,
"name": String,
"lat": Number,
"lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
POST
| /companies/{company_id}/fleets |
| This function adds a root fleet to a company. |
| company_id | the id of the desired company, or "mine" for the current user's company |
| name | String |
| lat | Number |
| lng | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | fleets |
| requires | at least company administrator user level |
| returns | the id of the new fleet |
| {"fleet_id": Number} |
|
GET
| /fleets |
| This function returns a list of the root fleets accessible to the current user. |
| see | fleets |
| requires | at least department administrator user level |
| returns | the list of fleets |
| [
{
"fleet_id": Number,
"name": String,
"lat": Number,
"lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
GET
| /fleets/{fleet_id}/fleets |
| This function returns a list of the subfleets corresponding to a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | fleets |
| requires | at least department administrator user level |
| returns | the list of fleets |
| [
{
"fleet_id": Number,
"name": String,
"lat": Number,
"lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
POST
| /fleets/{fleet_id}/fleets |
| This function adds a subfleet to a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| lat | Number |
| lng | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | fleets |
| requires | at least company administrator user level |
| returns | the id of the new fleet |
| {"fleet_id": Number} |
|
GET
| /fleets/{fleet_id} |
| This function returns detailed information about a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | fleets |
| requires | at least department administrator user level |
| returns | {
"fleet_id": Number,
"name": String,
"lat": Number,
"lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
} |
|
PATCH
| /fleets/{fleet_id} |
| This function updates the information of a fleet.
Company administrators are allowed to update any fleet belonging to their company. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| lat | Number |
| lng | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | fleets |
| requires | at least department administrator user level |
|
DELETE
| /fleets/{fleet_id} |
| This function deletes a fleet. |
| fleet_id | the id of the desired fleet |
| see | fleets |
| requires | at least company administrator user level |
| note | this function recursively and permanently deletes all the objects related to this fleet |
|
GET
| /fleets/{fleet_id}/vehicles |
| This function returns a list of the vehicles corresponding to a given fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | vehicles |
| returns | the list of vehicles |
| [
{
"vehicle_id": Number,
"name": String,
"license_plate": String,
"vin": String,
"maker": String,
"model": String,
"year_of_manufacture": Number,
"identification_card": String,
"type": Number,
"working_schedule": {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
}
},
"map_prefs": {
"color": String, ,
"size": String,
},
"default_driver": String,
"default_driver_phone": String,
"tracked": Boolean,
"device_serial_number": String,
"current_info": {
"lat": Number,
"lng": Number,
"speed": Number,
"moment": String,
"last_sync": String,
"azimuth": Number,
"driver_id": Number,
"satellites": Number,
"pdop": Number,
"status": Number,
"engine_since": String,
"navig_state": Number,
"battery_soc": Number,
"vrob": Number,
"charging_cable_connected": Boolean,
"battery_charging": Boolean,
"fuel_level": Number,
"total_fuel_used": Number,
"purpose": String,
"journey_code": String,
"contacts": {
input_id: Number,
...
},
"temperatures": {
"1": Number,
"2": Number,
"3": Number,
"4": Number
}
}
},
...
] |
|
POST
| /fleets/{fleet_id}/vehicles |
| This function adds a new vehicle to a fleet |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| license_plate | String |
| vin | String |
| maker | String |
| model | String |
| year_of_manufacture | Number |
| identification_card | String |
| type | Number |
| map_prefs | {
"color": String,
"size": String
} |
| working_schedule | {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
'from_minute": Number,
'to_hour": Number,
"to_minute": Number
}
} |
| default_driver | String |
| default_driver_phone | String |
| see | vehicles |
| returns | the id of the new vehicle |
| {"vehicle_id": Number} |
|
GET
| /fleets/{fleet_id}/vehicles/journeys |
| This function returns the journeys of all the vehicles corresponding to a given fleet that started or ended within a
specified period of time. If no start_moment or no stop_moment is given, the function returns the last journey
of each vehicle. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| min_distance | Number |
| if given, will filter out journeys with a distance less than this value (in kilometers) |
| min_duration | Number |
| if given, will filter out journeys with a duration less than this value (in seconds) |
| see | journeys |
| requires | tracked vehicles |
| note | ‣ the interval of time must be less than a month |
| ‣ when requesting the last journey, the min_distance and min_duration filters are ignored |
| ‣ when requesting the last journey, if the journey is in progress, the fields stop, distance,
idle_duration, max_speed and consumption will be null |
| returns | the list of journeys for each vehicle |
| [
{
"vehicle_id": String,
"journeys": [
{
"journey_id": String,
"start": {
"moment": String,
"lat": Number,
"lng": Number
},
"stop": {
"moment": String,
"lat": Number,
"lng": Number
},
"distance": Number,
"idle_duration": Number,
"consumption": {
"value": Number,
"measured": Boolean
},
"max_speed": Number,
"driver_id": Number,
"purpose": String,
"journey_code": String
},
...
]
},
...
] |
|
GET
| /fleets/{fleet_id}/vehicles/attributes |
| This function returns the attributes of all the vehicles corresponding to a given fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | attributes |
| returns | the list of attributes for each vehicle |
| [
{
"vehicle_id": String,
"attributes": [
{
"name": String,
"slug": String,
"type": Number,
"value": Number|Boolean|String
},
...
]
},
...
] |
|
GET
| /fleets/{fleet_id}/vehicles/fuelings |
| This function returns the fuelings of all the vehicles corresponding to a given fleet, within a given period of
time. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | fuelings |
| returns | the list of fuelings for each vehicle |
| [
{
"vehicle_id": String,
"fuelings": [
{
"moment": String,
"quantity": Number,
"price": Number,
"type": Number,
"provider": String,
"odometer": Number,
"station": String,
"card": String,
"remark": String
},
...
]
},
...
] |
|
GET
| /fleets/{fleet_id}/vehicles/odometers |
| This function returns the odometers of all the vehicles corresponding to a given fleet, at a certain moment.
Odometers can be computed using values from two sources: device (FMS) and dashboard reading. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| moment | String |
| the desired moment (defaults to now if not supplied) |
| see | vehicles |
| returns | the odometer for each vehicle |
| [
{
"vehicle_id": String,
"odometer": Number,
"source": String
},
...
] |
|
GET
| /vehicles |
| This function returns a list of all vehicles accessible to the current user. |
| see | vehicles |
| returns | the list of vehicles |
| [
{
"vehicle_id": Number,
"name": String,
"license_plate": String,
"vin": String,
"maker": String,
"model": String,
"year_of_manufacture": Number,
"identification_card": String,
"type": Number,
"working_schedule": {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
}
},
"map_prefs": {
"color": String, ,
"size": String,
},
"default_driver": String,
"default_driver_phone": String,
"tracked": Boolean,
"device_serial_number": String,
"current_info": {
"lat": Number,
"lng": Number,
"speed": Number,
"moment": String,
"last_sync": String,
"azimuth": Number,
"driver_id": Number,
"satellites": Number,
"pdop": Number,
"status": Number,
"engine_since": String,
"navig_state": Number,
"battery_soc": Number,
"vrob": Number,
"charging_cable_connected": Boolean,
"battery_charging": Boolean,
"fuel_level": Number,
"total_fuel_used": Number,
"purpose": String,
"journey_code": String,
"contacts": {
input_id: Number,
...
},
"temperatures": {
"1": Number,
"2": Number,
"3": Number,
"4": Number
}
}
},
...
] |
|
GET
| /vehicles/{vehicle_id} |
| This function returns detailed information about a vehicle. |
| vehicle_id | the id of the desired vehicle |
| see | vehicles |
| returns | {
"name": String,
"license_plate": String,
"vin": String,
"maker": String,
"model": String,
"year_of_manufacture": Number,
"identification_card": String,
"type": Number,
"working_schedule": {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
}
},
"map_prefs": {
"color": String, ,
"size": String,
},
"default_driver": String,
"default_driver_phone": String,
"tracked": Boolean,
"device_serial_number": String,
"current_info": {
"lat": Number,
"lng": Number,
"speed": Number,
"moment": String,
"last_sync": String,
"azimuth": Number,
"driver_id": Number,
"satellites": Number,
"pdop": Number,
"status": Number,
"engine_since": String,
"navig_state": Number,
"battery_soc": Number,
"battery_voltage": Number,
"vrob": Number,
"charging_cable_connected": Boolean,
"battery_charging": Boolean,
"fuel_level": Number,
"total_fuel_used": Number,
"purpose": String,
"journey_code": String,
"contacts": {
input_id: Number,
...
},
"axle_weight": Number,
"axle_weights": [Number, Number, ...],
"accel_pedal": Number,
"temperatures": {
"1": Number,
"2": Number,
"3": Number,
"4": Number
}
}
} |
|
PATCH
| /vehicles/{vehicle_id} |
| This function updates the information of a vehicle. |
| fleet_id | Number |
| name | String |
| license_plate | String |
| vin | String |
| maker | String |
| model | String |
| year_of_manufacture | Number |
| identification_card | String |
| type | Number |
| map_prefs | {
"color": String,
"size": String
} |
| working_schedule | {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
'from_minute": Number,
'to_hour": Number,
"to_minute": Number
}
} |
| default_driver | String |
| default_driver_phone | String |
| see | vehicles |
|
DELETE
| /vehicles/{vehicle_id} |
| This function deletes a vehicle. |
| see | vehicles |
|
GET
| /vehicles/{vehicle_id}/odometer |
| This function returns the odometer of a vehicle at a certain moment.
Odometers can be computed using values from two sources: device (FMS) and dashboard reading. |
| vehicle_id | the id of the desired vehicle |
| moment | String |
| the desired moment (defaults to now if not supplied) |
| see | vehicles |
| requires | tracked vehicles |
| note | odometers that are not available will be returned as null |
| returns | {
"odometer": Number,
"source": String
} |
|
POST
| /vehicles/{vehicle_id}/odometers |
| This function adds a new odometer reading for a vehicle. |
| vehicle_id | the id of the desired vehicle |
| odometer | Number |
| the value of the odometer |
| moment | String |
| the moment at which the odometer was recorded |
|
GET
| /vehicles/{vehicle_id}/presences |
| This function returns the presences of a vehicle that were received within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| filter | String |
| set to plot to return a set of filtered presences optimized for plotting on a map |
| filter_dist_percent | Number |
| min distance between two successive presences, expressed as percent from total
distance (defaults to 0.01, i.e. 1%) |
| filter_angle_thresh | Number |
| min angle between two successive presences, expressed as sexagesimal degrees
(defaults to 10) |
| see | presences |
| requires | tracked vehicles |
| note | the interval of time must be less than a week |
| returns | [
{
"presence_id": String,
"moment": String,
"lat": Number,
"lng": Number,
"speed": Number,
"azimuth": Number,
"engine": Boolean
},
...
] |
|
POST
| /vehicles/{vehicle_id}/presences |
| This function adds a presence (a tracking data record) for a vehicle.
Most of the parameters are optional. It is recommended however to supply as many parameters
as are available at the moment of the call. |
| vehicle_id | the id of the desired vehicle |
| moment | String |
| the moment of the presence |
| current | Boolean |
| tells whether the information is current or from the past (defaults to true) |
| journey | Boolean |
| the journey (ignition) status |
| lat | Number |
| the latitude |
| lng | Number |
| the longitude |
| speed | Number |
| the speed (in km/h) |
| azimuth | Number |
| the azimuth (degrees, from 0 to 360) |
| driver_key | String |
| the authenticated driver key |
| rel_odom | Number |
| a relative odometer used to determine travelled distance (in meters) |
| abs_odom | Number |
| the absolute (dashboard) odometer (in meters) |
| purpose | String |
| the journey purpose |
| journey_code | String |
| optional journey code |
| idling | Number |
| the idling time during current journey (in seconds) |
| event_type | String |
| the type of an event (see event types) |
| duration | Number |
| the duration of the event (in seconds) |
| input_id | Number |
| the id of an input (see input ids) |
| input_value | Number |
| the value of the input |
| fuel_level | Number |
| the current fuel level (the unit and scale depends on the vehicle configuration) |
| fuel_used | Number |
| the total fuel used (in liters) |
| rpm | Number |
| the engine RPM |
| temp | Boolean |
| the value of the first temperature sensor (in degrees Celsius) |
| temp2 | Number |
| the value of the second temperature sensor (in degrees Celsius) |
| temp3 | Number |
| the value of the third temperature sensor (in degrees Celsius) |
| temp4 | Number |
| the value of the fourth temperature sensor (in degrees Celsius) |
| auto_pos | if set to true, position fields (lat, lng and azimuth) will be automatically filled in
using last known values, if not supplied |
| see | presences |
| requires | tracked vehicles |
|
GET
| /vehicles/{vehicle_id}/journeys |
| This function returns the journeys of a vehicle that started or ended within a specified period of time.
If no start_moment or no stop_moment is given, the function returns the last journey of the vehicle. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| min_distance | Number |
| if given, will filter out journeys with a distance less than this value (in kilometers) |
| min_duration | Number |
| if given, will filter out journeys with a duration less than this value (in seconds) |
| see | journeys |
| requires | tracked vehicles |
| note | ‣ the interval of time must be less than a year |
| ‣ when requesting the last journey, the min_distance and min_duration filters are ignored |
| ‣ when requesting the last journey, if the journey is in progress, the fields stop, distance,
idle_duration, max_speed and consumption will be null |
| returns | [
{
"vehicle_id": Number,
"journey_id": String,
"start": {
"moment": String,
"lat": Number,
"lng": Number
},
"stop": {
"moment": String,
"lat": Number,
"lng": Number
},
"distance": Number,
"idle_duration": Number,
"consumption": {
"value": Number,
"measured": Boolean
},
"max_speed": Number,
"driver_id": Number,
"purpose": String,
"journey_code": String
},
...
] |
|
PATCH
| /vehicles/{vehicle_id}/journeys/{journey_id} |
| This function updates a journey. |
| vehicle_id | the id of the desired vehicle |
| journey_id | String |
| the id of the desired journey |
| journey_code | String |
| the new journey code |
| see | journeys |
|
GET
| /vehicles/{vehicle_id}/events |
| This function returns the events of a vehicle that occurred within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| type | String |
| if given, will return only the events of this type (see event types) |
| see | events |
| requires | tracked vehicles |
| note | the interval of time must be less than a year |
| returns | [
{
"event_id": String,
"moment": String,
"lat": Number,
"lng": Number,
"type": String,
"driver_id": Number,
"track_id": Number,
"roi_id": Number
},
...
] |
|
GET
| /vehicles/{vehicle_id}/attributes |
| This function returns the attributes of a vehicle. |
| vehicle_id | the id of the desired vehicle |
| see | attributes |
| returns | [
{
"slug": String,
"name": String,
"type": Number,
"value": Number|Boolean|String
},
...
] |
|
PATCH
| /vehicles/{vehicle_id}/attributes |
| This function sets the values of one or more vehicle attributes. |
| vehicle_id | the id of the desired vehicle |
| {body} | [
{
"slug": String,
"value": Number
Boolean
String
},
...
] |
| see | attributes |
|
PATCH
| /vehicles/{vehicle_id}/attributes/{slug} |
| This function sets the value of a vehicle attribute. |
| vehicle_id | the id of the desired vehicle |
| slug | String |
| the slug (simplified name) of the attribute |
| value | any |
| the new value of the attribute |
| see | attributes |
|
GET
| /vehicles/{vehicle_id}/fuelings |
| This function returns the fuelings of a vehicle that were done within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | fuelings |
| note | the interval of time must be less than a year |
| returns | [
{
"fueling_id": String,
"moment": String,
"quantity": Number,
"price": Number,
"type": Number,
"provider": String,
"odometer": Number,
"station": String,
"card": String,
"remark": String
},
...
] |
|
POST
| /vehicles/{vehicle_id}/fuelings |
| This function adds one or more fuelings of a vehicle to the system. |
| vehicle_id | the id of the desired vehicle |
| fuelings | [
{
"moment": String,
"quantity": Number,
"price": Number,
"type": Number,
"provider": String,
"odometer": Number,
"station": String,
"card": String,
"remark": String
},
...
] |
| a list of fuelings |
| see | fuelings |
| returns | the indexes of duplicate fuelings, if any |
| {"duplicate_indexes": [Number]} |
|
GET
| /vehicles/{vehicle_id}/device_settings |
| This function returns the available device settings of a vehicle (not including their values). |
| vehicle_id | the id of the desired vehicle |
| see | device settings |
| requires | tracked vehicles |
| returns | {
: {
"pretty": String,
"type": "int"|"bool"|"str"|"choices",
"unit": String,
"min": Number,
"max": Number,
"choices": [
{"value": Number, "pretty": String},
...
]
},
...
} |
|
GET
| /vehicles/{vehicle_id}/device_settings/{name} |
| This function queries the vehicle's device for a given setting and returns the corresponding value.
Not all settings are exposed by all vehicles. |
| vehicle_id | the id of the desired vehicle |
| name | String |
| the name of the device setting |
| see | device settings |
| requires | tracked vehicles |
| returns | ‣ the current value of the setting, if everything goes well |
| {"value": any} |
| ‣ a message set to whatever error has occurred, if any |
| {"message": String} |
|
PATCH
| /vehicles/{vehicle_id}/device_settings/{name} |
| This function updates a vehicle's device setting. |
| vehicle_id | the id of the desired vehicle |
| name | String |
| the name of the device setting |
| value | any |
| the new value for the device setting |
| see | device settings |
| requires | tracked vehicles |
| returns | a message set to whatever error has occurred, if any |
| {"message": String} |
|
GET
| /vehicles/{vehicle_id}/tolling |
| This function returns the current status of the tolling services associated to this vehicle. |
| vehicle_id | the id of the desired vehicle |
| returns | {
"hugo": {
"obu_id": String,
"obu_status": Number,
"service_status": Number,
"balance_status": Number
},
"pltoll": {
"obu_id": String,
"obu_status": Number,
"service_status": Number,
"balance_status": Number
},
"bgtoll": {
"obu_id": String,
"obu_status": Number,
"service_status": Number,
"balance_status": Number
}
} |
|
GET
| /vehicles/{vehicle_id}/temperatures |
| This function returns the temperature records of a vehicle that were generated within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| type | String |
| see | temperatures |
| requires | tracked vehicles |
| note | the interval of time must be less than a year |
| returns | [
{
"temperature_id": Number,
"vehicle_id": Number,
"moment": String,
"temp": Number,
"temp2": Number,
"temp3": Number,
"temp4": Number,
"moment": String,
"lat": Number,
"lng": Number
},
...
] |
|
GET
| /fleets/{fleet_id}/vehicles/hourmeters |
| This function returns the hourmeters of all the vehicles corresponding to a given fleet, at a certain moment.
Odometers can be computed using values from two sources: device (FMS) and dashboard reading. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| moment | String |
| the desired moment (defaults to now if not supplied) |
| see | vehicles |
| returns | the hourmeter for each vehicle |
| [
{
"vehicle_id": String,
"hourmeter": Number,
"source": String
},
...
] |
|
GET
| /vehicles/{vehicle_id}/fuel_levels |
| This function returns the fuel levels of one vehicle that were received within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | vehicles |
| requires | a tracked vehicle |
| note | the interval of time must be less than a week |
| returns | ‣ a list with each element a dictionary with the keys:
-moment: the moment when the data was read
-fuel_level: the amount of fuel available in the tanks (percentage - value between 0.0 and 100.0)
-fuel_level_tanks: a list with the remaining fuel level (percentage: see above) for available tanks
(the list always has 3 elements, if only one or two tanks are missing, the last element/s will be None) |
| [
{
"moment": String
"fuel_level": Float,
"fuel_level_tanks": []
},
...
] |
| ‣ a message with what went wrong if something is not ok |
| {"message": String} |
|
GET
| /vehicles/journeys/{journey_id} |
| This function returns a specific journey |
| journey_id | the id of the desired journey |
| see | journeys |
| returns | {
"vehicle_id": Number,
"journey_id": String,
"start": {
"moment": String,
"lat": Number,
"lng": Number
},
"stop": {
"moment": String,
"lat": Number,
"lng": Number
},
"distance": Number,
"idle_duration": Number,
"consumption": {
"value": Number,
"measured": Boolean
},
"max_speed": Number,
"driver_id": Number,
"purpose": String,
"journey_code": String
} |
|
POST
| /vehicles/{vehicle_id}/hourmeters |
| This function adds a new hourmeter reading for a vehicle. |
| vehicle_id | Number |
| the id of the desired vehicle obtained with a previous get_vehicles call |
| hourmeter | Number |
| the value of the hourmeter |
| moment | String |
| the moment at which the hourmeter was recorded |
| returns | the message "ok" |
| {"message": String} |
|
GET
| /vehicles/{vehicle_id}/hourmeter |
| This function returns the hourmeter of one or more vehicles at a certain moment.
Odometers can be computed using values from two sources: device (FMS) and dashboard reading. |
vehicle_id
vehicle_ids | Number
[Number] |
| the id of the desired vehicle or a comma-separated list of ids,
obtained with a previous get_vehicles call |
| moment | String |
| the desired moment (defaults to now if not supplied) |
| see | vehicles |
| requires | tracked vehicles |
| note | hourmeters that are not available will be returned as null |
| returns | ‣ a single object if vehicle_id is given |
| {
"vehicle_id": String,
"hourmeter": Number,
"source": String
} |
| ‣ a list of objects if vehicle_ids is given |
| [
{
"vehicle_id": String,
"hourmeter": Number,
"source": String
},
...
] |
|
GET
| /vehicles/computed_route |
| This function returns information about route for the specified vehicles and a set of coordinates |
vehicle_id
vehicle_ids | Number
[Number] |
| an id or a comma-separated list of ids for the desired vehicle(s) |
| lat | Number |
| the latitude of the final position |
| lng | Number |
| the longitude of the final position |
| returns | a list with information for the vehicles |
| [
{
"vehicle_id": Number,
"estimated_distance": Number,
"estimated_duration": String,
"estimated_time": Number,
"estimated_cost": {
"total_cost": Number,
"currency": String
},
"leave_in": Number
},
...
] |
|
GET
| /vehicles/{vehicle_id}/rpm |
| This function returns the rpm levels of one vehicle that were received within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | vehicles |
| requires | a tracked vehicle |
| note | the interval of time must be less than a week |
| returns | ‣ a list with rpm levels if everything is ok |
| [
{
"rpm": Integer,
"moment": String
},
...
] |
| ‣ a message with what went wrong if something is not ok |
| {"message": String} |
|
GET
| /vehicles/{vehicle_id}/tickets |
| This function returns the tickets of a vehicle that were opened within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | tickets |
| returns | [
{
"ticket_id": Number,
"reporter_id": Number,
"responsible_id": Number,
"issue": String,
"remark": String,
"opened_moment": String,
"status": Number
},
...
] |
|
POST
| /vehicles/{vehicle_id}/tickets |
| This function creates a ticket for a vehicle. |
| vehicle_id | the id of the desired fleet |
| reporter_id | Number |
| the id of the reporter |
| responsible_id | Number |
| the id of the responsible |
| issue | String |
| the description of the ticket's issue |
| remark | String |
| an optional textual remark |
| see | tickets |
| returns | the id of the new ticket |
| {"ticket_id": Number} |
|
PATCH
| /tickets/{ticket_id} |
| This function updates the information of a ticket. |
| ticket_id | the id of the desired ticket |
| responsible_id | Number |
| issue | String |
| remark | String |
| status | Number |
| see | tickets |
|
GET
| /vehicles/{vehicle_id}/temporary_links |
| This function returns the temporary links of a vehicle. |
| vehicle_id | the id of the desired vehicle |
| see | temporary links |
| returns | [
{
"temporary_link_id": Number,
"link": String,
"expiry_moment": String,
"trajectory_days": Number,
"message": String
},
...
] |
|
POST
| /vehicles/{vehicle_id}/temporary_links |
| This function creates a temporary link for a vehicle. |
| vehicle_id | the id of the desired vehicle |
| expiry_moment | String |
| the moment when the link expires |
| message | String |
| an optional associated message |
| trajectory_days | Number |
| the number of days of trajectory to display (defaults to 0) |
| see | temporary links |
| returns | the id of the new temporary link |
| {"temporary_link_id": Number} |
|
PATCH
| /temporary_links/{temporary_link_id} |
| This function updates the information of a temporary link. |
| temporary_link_id | the id of the desired temporary link |
| expiry_moment | String |
| the moment when the link expires |
| message | String |
| an associated message (defaults to the vehicle name) |
| trajectory_days | Number |
| the number of days of trajectory to display (defaults to 0) |
| see | temporary links |
|
DELETE
| /temporary_links/{temporary_link_id} |
| This function deletes a temporary link. |
| temporary_link_id | the id of the desired temporary link |
| see | temporary links |
|
GET
| /fleets/{fleet_id}/users |
| This function returns a list of the users corresponding to a given fleet.
Company administrators are allowed list all users of their company.
Department administrators are allowed to list the users of their department or subdepartments. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | users |
| requires | at least department admin user level |
| returns | the list of users |
| [
{
"user_id": Number,
"username": String,
"first_name": String,
"last_name": String,
"email": String,
"phone": String,
"timezone": String,
"timezone_offset": Number,
"units": Number,
"has_2fa": Boolean,
"profile_photo": String,
"level": Number
},
...
] |
|
POST
| /fleets/{fleet_id}/users |
| This function adds a new user to a fleet.
The level cannot have a value smaller than the current user's level. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| username | String |
| password | String |
| first_name | String |
| last_name | String |
| email | String |
| phone | String |
| timezone | String |
| units | Number |
| has_2fa | Boolean |
| profile_photo | String |
| level | Number |
| send_email | Boolean |
| if set to true will send email with credentials to the created user if email address specified |
| language | String |
| language ISO code |
| see | users |
| requires | at least department admin user level |
| returns | the id of the new user |
| {"user_id": Number} |
|
GET
| /users |
| This function returns a list of all users accessible to the current user.
Company administrators are allowed list all users of their company.
Department administrators are allowed to list the users of their department or subdepartments. |
| see | users |
| requires | at least department admin user level |
| returns | the list of users |
| [
{
"user_id": Number,
"username": String,
"first_name": String,
"last_name": String,
"email": String,
"phone": String,
"timezone": String,
"timezone_offset": Number,
"units": Number,
"has_2fa": Boolean,
"profile_photo": String,
"level": Number
},
...
] |
|
GET
| /users/{user_id} |
| This function returns detailed information about a user.
All users are allowed to obtain information about any of the users of their company,
provided they know the id. |
| user_id | the id of the desired user, or "me" for the current user |
| see | users |
| returns | {
"user_id": Number,
"username": String,
"first_name": String,
"last_name": String,
"email": String,
"phone": String,
"timezone": String,
"timezone_offset": Number,
"units": Number,
"has_2fa": Boolean,
"profile_photo": String,
"level": Number
} |
|
PATCH
| /users/{user_id} |
| This function updates the information of a user.
Company administrators are allowed to update other users of their company.
Department administrators are allowed to update other users of their department or subdepartments.
The level cannot have a value smaller than the current user's level. |
| user_id | the id of the desired user, or "me" for the current user |
| fleet_id | Number |
| username | String |
| first_name | String |
| last_name | String |
| email | String |
| phone | String |
| timezone | String |
| units | Number |
| has_2fa | Boolean |
| profile_photo | String |
| level | Number |
| see | users |
|
DELETE
| /users/{user_id} |
| This function deletes a user. |
| user_id | the id of the desired user |
| see | users |
| requires | at least department admin user level |
|
GET
| /users/{user_id}/notification_prefs |
| This function returns the notification preferences of a user.
These notification preferences include the types of notifications,
the events for which notifications are sent. |
| user_id | the id of the desired user, or "me" for the current user |
| see | users |
| note | the number associated to the expiry attributes is the number of days to notify in advance (1, 7 or 30) |
| returns | {
"user_id": Number,
"events": {
event type: {
"online": Boolean,
"email": Boolean,
"sms": Boolean
},
...
},
"expiry": {
attribute name: Number,
...
}
} |
|
PATCH
| /users/{user_id}/notification_prefs |
| This function updates the notifications preferences of a user.
Company administrators are allowed to update other users of their company.
Department administrators are allowed to update other users of their department or subdepartments. |
| user_id | the id of the desired user, or "me" for the current user |
| events | {
event type: {
"online": Boolean,
"email": Boolean,
"sms": Boolean
},
...
} |
| expiry | {
attribute name: Number,
...
} |
| see | users |
| note | the number associated to the expiry attributes is the number of days to notify in advance (1, 7 or 30) |
|
GET
| /users/{user_id}/geofence_prefs |
| This function returns the geofence preferences of a user.
These geofence preferences are in fact the tracks and regions of interest
that the user wishes to use as geofences, in association with one or more vehicles (see geofence events in event types). |
| user_id | the id of the desired user, or "me" for the current user |
| see | users, tracks, regions of interest |
| note | ‣ a "vehicle_id": 0 signifies any vehicle,
a "roi_id": 0 signifies any region of interest
and "track_id": 0 signifies any track |
| ‣ one of roi_id and track_id is set and the other one is null, indicating the type of geofence |
| returns | {
"user_id": Number,
"geofences": [
{
"vehicle_id": Number,
"roi_id": Number,
"track_id": Number
},
...
]
} |
|
PATCH
| /users/{user_id}/geofence_prefs |
| This function updates the geofence preferences of a user.
Company administrators are allowed to update other users of their company.
Department administrators are allowed to update other users of their department or subdepartments. |
| user_id | the id of the desired user, or "me" for the current user |
| geofences | [
{
"vehicle_id": Number,
"roi_id": Number,
"track_id": Number
},
...
] |
| see | users, tracks, regions of interest |
| note | ‣ a "vehicle_id": 0 signifies any vehicle, a "roi_id": 0 signifies any region of interest and
"track_id": 0 signifies any track |
| ‣ one of roi_id and track_id must be set and the other one must be null, indicating the type of geofence |
|
PATCH
| /users/{user_id}/password |
| This function updates the password of the current user.
Only the current user's password can be updated.
If token is given, it is expected to be a token from password reset initialization routine.
At least one of old_password and token must be supplied. |
| user_id | always "me" |
| password | String |
| old_password | String |
| token | String |
| see | users |
|
POST
| /users/reset_password |
| This function performs the password reset procedure for the user with the given password. |
| email | String |
| see | users |
|
GET
| /fleets/{fleet_id}/drivers |
| This function returns a list of the drivers corresponding to a given fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | drivers |
| note | tacho field will be null if tachograph information is not available |
| returns | the list of drivers |
| [
{
"driver_id": Number,
"name": String,
"email": String,
"phone": String,
"personal_identification": String,
"key_code": String,
"driver_code": String,
"active": Boolean,
"fcm_id": String,
"tacho": {
"state": Number,
"time_driven_since_short_break": Number,
"time_driven_since_long_rest": Number,
"leave_in": Number,
"next_short_break_in": Number,
"next_long_rest_in": Number
}
},
...
] |
|
POST
| /fleets/{fleet_id}/drivers |
| This function adds a new driver to a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| email | String |
| phone | String |
| personal_identification | String |
| key_code | String |
| driver_code | String |
| active | Boolean |
| fcm_id | String |
| ds_timezone | String, |
| day_shift | {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
'from_minute": Number,
'to_hour": Number,
"to_minute": Number
}
} |
| see | drivers |
| returns | the id of the new driver |
| {"driver_id": Number} |
|
GET
| /fleets/{fleet_id}/drivers/attributes |
| This function returns the attributes of all the drivers corresponding to a given fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | attributes |
| returns | the list of attributes for each driver |
| [
{
"driver_id": String,
"attributes": [
{
"name": String,
"slug": String,
"type": Number,
"value": Number|Boolean|String
},
...
]
},
...
] |
|
GET
| /drivers |
| This function returns a list of the drivers visible to the current user. |
| see | drivers |
| note | tacho field will be null if tachograph information is not available |
| returns | the list of drivers |
| [
{
"driver_id": Number,
"name": String,
"email": String,
"phone": String,
"personal_identification": String,
"key_code": String,
"driver_code": String,
"active": Boolean,
"fcm_id": String,
"tacho": {
"state": Number,
"time_driven_since_short_break": Number,
"time_driven_since_long_rest": Number,
"leave_in": Number,
"next_short_break_in": Number,
"next_long_rest_in": Number
}
},
...
] |
|
GET
| /drivers/{driver_id} |
| This function returns detailed information about a driver. |
| driver_id | the id of the desired driver |
| see | drivers |
| note | tacho field will be null if tachograph information is not available |
| returns | {
"driver_id": Number,
"name": String,
"email": String,
"phone": String,
"personal_identification": String,
"key_code": String,
"driver_code": String,
"ds_timezone": String,
"day_shift": {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
}
},
"active": Boolean,
"fcm_id": String,
"tacho": {
"state": Number,
"time_driven_since_short_break": Number,
"time_driven_since_long_rest": Number,
"leave_in": Number,
"next_short_break_in": Number,
"next_long_rest_in": Number
}
} |
|
PATCH
| /drivers/{driver_id} |
| This function updates the information of a driver. |
| driver_id | the id of the desired driver |
| fleet_id | Number |
| name | String |
| email | String |
| phone | String |
| personal_identification | String |
| key_code | String |
| driver_code | String |
| active | Boolean |
| fcm_id | String |
| ds_timezone | String, |
| day_shift | {
"mon": {
"from_hour": Number,
"from_minute": Number,
"to_hour": Number,
"to_minute": Number
},
...,
"sun": {
"from_hour": Number,
'from_minute": Number,
'to_hour": Number,
"to_minute": Number
}
} |
| see | drivers |
|
DELETE
| /drivers/{driver_id} |
| This function deletes a driver. |
| driver_id | the id of the desired driver |
| see | drivers |
|
PATCH
| /drivers/{driver_id}/attributes/{slug} |
| This function sets the value of a driver attribute. |
| driver_id | the id of the desired driver |
| slug | String |
| the slug (simplified name) of the attribute |
| value | any |
| the new value of the attribute |
| see | attributes |
|
GET
| /drivers/{driver_id}/attributes |
| This function returns the attributes of a driver. |
| driver_id | the id of the desired driver |
| see | attributes |
| returns | [
{
"slug": String,
"name": String,
"type": Number,
"value": Number|Boolean|String
},
...
] |
|
GET
| /companies/{company_id}/driver_groups |
| This function returns a list of the driver groups corresponding to a given company. |
| company_id | the id of the desired company, or "mine" for the current user's company |
| see | driver groups |
| requires | at least company administrator user level |
| returns | the list of driver groups |
| [
{
"driver_group_id": Number,
"name": String,
"driver_ids": [Number]
},
...
] |
|
POST
| /companies/{company_id}/driver_groups |
| This function adds a new driver group to a company. |
| company_id | the id of the desired company, or "mine" for the current user's company |
| name | String |
| driver_ids | [Number] |
| see | driver groups |
| requires | at least company administrator user level |
| returns | the id of the new driver group |
| {"driver_group_id": Number} |
|
GET
| /driver_groups |
| This function returns a list of the driver groups accessible to the current user. |
| see | driver groups |
| requires | at least company administrator user level |
| returns | the list of driver groups |
| [
{
"driver_group_id": Number,
"name": String,
"driver_ids": [Number]
},
...
] |
|
GET
| /driver_groups/{driver_group_id} |
| This function returns detailed information about a driver group. |
| driver_group_id | the id of the desired driver group |
| see | driver groups |
| requires | at least company administrator user level |
| returns | {
"driver_group_id": Number,
"name": String,
"driver_ids": [Number]
} |
|
PATCH
| /driver_groups/{driver_group_id} |
| This function updates the information of a driver group. |
| driver_group_id | the id of the desired driver group |
| name | String |
| driver_ids | [Number] |
| see | driver groups |
| requires | at least company administrator user level |
|
DELETE
| /driver_groups/{driver_group_id} |
| This function deletes a driver group. |
| driver_group_id | the id of the desired driver group |
| see | driver groups |
| requires | at least company administrator user level |
|
GET
| /fleets/{fleet_id}/pois |
| This function returns a list of the points of interest corresponding to a given fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | points of interest |
| returns | the list of POIs |
| [
{
"poi_id": Number,
"name": String,
"category": String,
"comment": String,
"business": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"lat": Number,
"lng": Number,
"delta_lat": Number,
"delta_lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
POST
| /fleets/{fleet_id}/pois |
| This function adds a new point of interest to a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| category | String |
| comment | String |
| business | Boolean |
| visible_upwards | Boolean |
| visible_downwards | Boolean |
| lat | Number |
| lng | Number |
| delta_lat | Number |
| delta_lng | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | points of interest |
| returns | the id of the new point of interest |
| {"poi_id": Number} |
|
GET
| /pois |
| This function returns a list of the points of interest accessible to the current user. |
| see | points of interest |
| returns | the list of POIs |
| [
{
"poi_id": Number,
"name": String,
"category": String,
"comment": String,
"business": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"lat": Number,
"lng": Number,
"delta_lat": Number,
"delta_lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
GET
| /pois/{poi_id} |
| This function returns detailed information about a point of interest. |
| poi_id | the id of the desired point of interest |
| see | points of interest |
| returns | {
"poi_id": Number,
"name": String,
"category": String,
"comment": String,
"business": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"lat": Number,
"lng": Number,
"delta_lat": Number,
"delta_lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
} |
|
PATCH
| /pois/{poi_id} |
| This function updates the information of a point of interest. |
| poi_id | the id of the desired point of interest |
| fleet_id | Number |
| name | String |
| category | String |
| comment | String |
| business | Boolean |
| visible_upwards | Boolean |
| visible_downwards | Boolean |
| lat | Number |
| lng | Number |
| delta_lat | Number |
| delta_lng | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | points of interest |
|
DELETE
| /pois/{poi_id} |
| This function deletes a point of interest. |
| poi_id | the id of the desired point of interest |
| see | points of interest |
|
GET
| /pois/public |
| This function returns a list of the public points of interest. |
| see | points of interest |
| returns | the list of public POIs |
| [
{
"poi_id": Number,
"name": String,
"category": String,
"comment": String,
"business": Boolean,
"lat": Number,
"lng": Number,
"delta_lat": Number,
"delta_lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
POST
| /pois/public |
| This function adds a new public point of interest. |
| name | String |
| category | String |
| comment | String |
| business | Boolean |
| visible_upwards | Boolean |
| visible_downwards | Boolean |
| lat | Number |
| lng | Number |
| delta_lat | Number |
| delta_lng | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | points of interest |
| requires | at least SafeFleet administrator user level |
| returns | the id of the new point of interest |
| {"poi_id": Number} |
|
GET
| /fleets/{fleet_id}/rois |
| This function returns a list of the regions of interest corresponding to a given fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| see | regions of interest |
| returns | the list of ROIs |
| [
{
"roi_id": Number,
"name": String,
"category": String,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"polygon": [
{
"lat": Number,
"lng": Number
},
...
]
},
...
] |
|
POST
| /fleets/{fleet_id}/rois |
| This function adds a new region of interest to a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| category | String |
| visible_upwards | Boolean |
| visible_downwards | Boolean |
| polygon | [
{
"lat": Number,
"lng": Number
},
...
] |
| see | regions of interest |
| returns | the id of the new region of interest |
| {"roi_id": Number} |
|
GET
| /rois |
| This function returns a list of the regions of interest accessible to the current user. |
| see | regions of interest |
| returns | the list of ROIs |
| [
{
"roi_id": Number,
"name": String,
"category": String,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"polygon": [
{
"lat": Number,
"lng": Number
},
...
]
},
...
] |
|
GET
| /rois/{roi_id} |
| This function returns detailed information about a region of interest. |
| roi_id | the id of the desired region of interest |
| see | regions of interest |
| returns | {
"roi_id": Number,
"name": String,
"category": String,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"polygon": [
{
"lat": Number,
"lng": Number
},
...
]
} |
|
PATCH
| /rois/{roi_id} |
| This function updates the information of a region of interest. |
| roi_id | the id of the desired region of interest |
| fleet_id | Number |
| name | String |
| category | String |
| visible_upwards | Boolean |
| visible_downwards | Boolean |
| polygon | [
{
"lat": Number,
"lng": Number
},
...
] |
| see | regions of interest |
|
DELETE
| /rois/{roi_id} |
| This function deletes a region of interest. |
| roi_id | the id of the desired region of interest |
| see | regions of interest |
|
GET
| /rois/public |
| This function returns a list of the public regions of interest. |
| see | regions of interest |
| returns | the list of public ROIs |
| [
{
"roi_id": Number,
"name": String,
"category": String,
"polygon": [
{
"lat": Number,
"lng": Number
},
...
]
},
...
] |
|
POST
| /rois/public |
| This function adds a new public region of interest to a fleet. |
| name | String |
| category | String |
| polygon | [
{
"lat": Number,
"lng": Number
},
...
] |
| see | regions of interest |
| requires | at least SafeFleet administrator user level |
| returns | the id of the new region of interest |
| {"roi_id": Number} |
|
GET
| /fleets/{fleet_id}/tracks |
| This function returns a list of the tracks corresponding to a given fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| include_navig | Boolean |
| if true, will include tracks used as navigation jobs; defaults to false |
| see | tracks |
| returns | the list of tracks |
| [
{
"track_id": Number,
"name": String,
"geofence": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"pois": [
{
"poi_id": Number,
"order": Number,
"lat": Number,
"lng": Number
},
...
],
"way_points": [
{
"order": Number,
"lat": Number,
"lng": Number
},
...
]
},
...
] |
|
POST
| /fleets/{fleet_id}/tracks |
| This function adds a new track to a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| geofence | Boolean |
| visible_upwards | Boolean |
| visible_downwards | Boolean |
| pois | [
{
"poi_id": Number,
"order": Number
},
...
] |
| way_points | [
{
"order": Number,
"lat": Number,
"lng": Number
},
...
] |
| see | tracks |
| returns | the id of the new track |
| {"track_id": Number} |
|
GET
| /tracks |
| This function returns a list of the tracks visible to the current user. |
| include_navig | Boolean |
| if true, will include tracks used as navigation jobs; defaults to false |
| see | tracks |
| returns | the list of tracks |
| [
{
"track_id": Number,
"name": String,
"geofence": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"pois": [
{
"poi_id": Number,
"order": Number,
"lat": Number,
"lng": Number
},
...
],
"way_points": [
{
"order": Number,
"lat": Number,
"lng": Number
},
...
]
},
...
] |
|
GET
| /tracks/{track_id} |
| This function returns detailed information about a track. |
| track_id | the id of the desired track |
| see | tracks |
| returns | {
"track_id": Number,
"name": String,
"geofence": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"pois": [
{
"poi_id": Number,
"order": Number,
"lat": Number,
"lng": Number
},
...
],
"way_points": [
{
"order": Number,
"lat": Number,
"lng": Number
},
...
]
} |
|
PATCH
| /tracks/{track_id} |
| This function updates the information of a track. |
| track_id | the id of the desired track |
| fleet_id | Number |
| name | String |
| geofence | Boolean |
| visible_upwards | Boolean |
| visible_downwards | Boolean |
| pois | [
{
"poi_id": Number,
"order": Number
},
...
] |
| way_points | [
{
"order": Number,
"lat": Number,
"lng": Number
},
...
] |
| see | tracks |
|
DELETE
| /tracks/{track_id} |
| This function deletes a track. |
| track_id | the id of the desired track |
| see | tracks |
|
GET
| /fleets/{fleet_id}/navig_jobs |
| This function returns a list of the navigation jobs corresponding to a given fleet,
that were created within a given period of time. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | navigation jobs |
| returns | the list of navigation jobs |
| [
{
"navig_job_id": Number,
"name": String,
"message": String,
"remark": String,
"lat": Number,
"lng": Number,
"vehicle_id": Number,
"created": String,
"start": String,
"due": String,
"state": Number,
"poi_id": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
POST
| /fleets/{fleet_id}/navig_jobs |
| This function creates a new navigation job in a fleet. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| name | String |
| message | String |
| remark | String |
| lat | Number |
| lng | Number |
| vehicle_id | Number |
| start | String |
| due | String |
| poi_id | Number |
| track_id | Number |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | navigation jobs |
| note | ‣ the state of the new job is always set to New;
see navigation job states for the available states |
| ‣ if poi_id is given, the job will be associated with that POI and the following
fields will be ignored: name, address, lat and lng |
| ‣ if track_id is given, the job will be associated with that track and the following
fields will be ignored: name, lat and lng |
| returns | the id of the new navigation job |
| {"navig_job_id": Number} |
|
GET
| /navig_jobs |
| This function returns a list of the navigation jobs that are accessible to the current user,
that were created within a given period of time. |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | navigation jobs |
| returns | the list of navigation jobs |
| [
{
"navig_job_id": Number,
"name": String,
"message": String,
"remark": String,
"lat": Number,
"lng": Number,
"vehicle_id": Number,
"created": String,
"start": String,
"due": String,
"state": Number,
"poi_id": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
...
] |
|
GET
| /navig_jobs/{navig_job_id} |
| This function returns detailed information about a navigation job. |
| navig_job_id | the id of the desired navigation job |
| see | navigation jobs |
| returns | {
"navig_job_id": Number,
"name": String,
"message": String,
"remark": String,
"lat": Number,
"lng": Number,
"vehicle_id": Number,
"created": String,
"start": String,
"due": String,
"state": Number,
"poi_id": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
} |
|
PATCH
| /navig_jobs/{navig_job_id} |
| This function updates the information of a navigation job. |
| navig_job_id | the id of the desired navigation job |
| name | String |
| message | String |
| remark | String |
| lat | Number |
| lng | Number |
| vehicle_id | Number |
| start | String |
| due | String |
| address | {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
} |
| see | navigation jobs |
| note | ‣ if the job is associated to a point of interest, then its name, address and location will be updated with the supplied values |
| ‣ a job cannot be modified unless it is New, Rejected, Cancelled or Completed;
see navigation job states for the available states |
|
DELETE
| /navig_jobs/{navig_job_id} |
| This function deletes a navigation job. |
| navig_job_id | the id of the desired navigation job |
| see | navigation jobs |
|
GET
| /fleets/{fleet_id}/carpool_reservations |
| This function returns a list of the carpool reservations corresponding to a given fleet,
that were created within a given period of time. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| use_created | Boolean |
| Use created moment instead of start/stop moments |
| see | carpool reservations |
| returns | the list of carpool reservations |
| [
{
"carpool_reservation_id": Number,
"vehicle_id": Number,
"user_id": Number,
"created": String,
"start": String,
"stop": String,
"cancelled": Boolean,
"remark": String
},
...
] |
|
POST
| /vehicles/{vehicle_id}/carpool_reservations |
| This function creates a new carpool reservation for a given vehicle.
If no user_id is supplied, the current user will be assumed. |
| vehicle_id | the id of the desired vehicle |
| user_id | Number |
| start | String |
| stop | String |
| remark | String |
| see | carpool reservations |
| returns | the id of the new carpool reservation |
| {"carpool_reservation_id": Number} |
|
GET
| /carpool_reservations |
| This function returns a list of the carpool reservations accessible to the current user,
that were created within a given period of time. |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| use_created | Boolean |
| Use created moment instead of start/stop moments |
| see | carpool reservations |
| returns | the list of carpool reservations |
| [
{
"carpool_reservation_id": Number,
"vehicle_id": Number,
"user_id": Number,
"created": String,
"start": String,
"stop": String,
"cancelled": Boolean,
"remark": String
},
...
] |
|
GET
| /carpool_reservations/{carpool_reservation_id} |
| This function returns detailed information about a carpool reservation. |
| carpool_reservation_id | the id of the desired carpool reservation |
| see | carpool reservations |
| returns | {
"carpool_reservation_id": Number,
"vehicle_id": Number,
"user_id": Number,
"created": String,
"start": String,
"stop": String,
"cancelled": Boolean,
"remark": String
} |
|
PATCH
| /carpool_reservations/{carpool_reservation_id} |
| This function updates the information of a carpool reservation. |
| carpool_reservation_id | the id of the desired carpool reservation |
| user_id | Number |
| start | String |
| stop | String |
| cancelled | Boolean |
| remark | String |
| see | carpool reservations |
|
GET
| /fleets/{fleet_id}/vehicles/documents |
| This function returns the documents of all the vehicles corresponding to a given fleet, within a given period of
time. |
| fleet_id | the id of the desired fleet, or "mine" for the current user's fleet |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | documents |
| returns | the list of fuelings for each vehicle |
| [
{
"vehicle_id": String,
"documents": [
{
"document_id": String,
"moment": String,
"content_type": String,
"name": String
},
...
]
},
...
] |
|
GET
| /vehicles/{vehicle_id}/documents |
| This function returns the documents of a vehicle, within a specified period of time. |
| vehicle_id | the id of the desired vehicle |
| start_moment | String |
| defines the beginning of the desired period of time |
| stop_moment | String |
| defines the end of the desired period of time |
| see | documents |
| note | the interval of time must be less than a year |
| returns | [
{
"document_id": String,
"moment": String,
"content_type": String,
"name": String
},
...
] |
|
POST
| /vehicles/{vehicle_id}/documents |
| This function adds a document to a vehicle. |
| vehicle_id | the id of the desired vehicle |
| name | String |
| the document name |
| moment | String |
| document moment (defaults to now) |
| content_type | String |
| the document content type (e.g. image/jpeg) |
| content | String |
| base64-encoded content |
| see | documents |
| note | maximum allowed document size is 10MB |
|
GET
| /documents/{document_id} |
| This function returns the details of a document. |
| document_id | the id of the desired document |
| see | documents |
| returns | {
"document_id": String,
"vehicle_id": Number,
"moment": String,
"name": String
"content_type": String,
"content": String
} |
|
DELETE
| /documents/{document_id} |
| This function deletes a document. |
| document_id | the id of the desired document |
| see | documents |
|
GET
| /flavours |
| This function return the available functionality flavours. |
| requires | at least SafeFleet administrator user level |
| returns | the list of flavours |
| {
"flavour1": {
"title": String,
"func1": any,
...
},
...
} |
|
GET
| /lookup_position |
| This function performs a position lookup for a (lat, lng) pair.
First, a search through all the points of interest accessible to the current user is done.
Then, if no point of interest matched, a reverse geocoding is performed.
If you need to look up more than one position, use lookup_positions instead. |
| lat | Number |
| the latitude of the position |
| lng | Number |
| the longitude of the position |
| force_address | Boolean |
| set this to true to force the return of a reverse-geocoded address, ignoring all POIs |
| lang | String |
| the language code (e.g. en-us) |
| note | either the point of interest is returned or the found address, never both; however both the point of
interest and the address may be null |
| returns | the "resolved" position |
| {
"display_name": String,
"poi": {
"poi_id": Number,
"name": String,
"category": String,
"comment": String,
"business": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"lat": Number,
"lng": Number,
"delta_lat": Number,
"delta_lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
"address": {
"lat": Number,
"lng": Number,
"country": String,
"state": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String
}
} |
|
POST
| /lookup_positions |
| This function performs a lookup for multiple positions made of (lat, lng) pairs.
First, a search through all the points of interest accessible to the current user is done.
Then, if no point of interest matched, a reverse geocoding is performed. |
| lat_lngs | [
{
"lat": Number,
"lng": Number
},
...
] |
| the list of positions |
| force_address | Boolean |
| set this to true to force the return of a reverse-geocoded address, ignoring all POIs |
| lang | String |
| the language code (e.g. en-us) |
| note | ‣ the list of coordinates must not be larger than 1000 elements |
| ‣ either the point of interest is returned or the found address, never both; however both the point of
interest and the address may be null |
| returns | the list of "resolved" positions, in respective order |
| [
{
"display_name": String,
"poi": {
"poi_id": Number,
"name": String,
"category": String,
"comment": String,
"business": Boolean,
"visible_upwards": Boolean,
"visible_downwards": Boolean,
"lat": Number,
"lng": Number,
"delta_lat": Number,
"delta_lng": Number,
"address": {
"country": String,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String,
"phone": String,
"email": String
}
},
"address": {
"lat": Number,
"lng": Number,
"country": String
"state": String,,
"county": String,
"city": String,
"street": String,
"number": String,
"postal_code": String
}
},
...
] |
- Tables Of Constants
Company Types
| Company Type | Description |
|---|
| "enterprise" | Enterprise |
| "self_employed" | Self-employed Individual |
| "individual" | Individual |
| "ngo" | Non-governmental Organization |
| "other" | Other |
Activity Types
| Activity Type | Description |
|---|
| "international_transport" | International Transport |
| "mining_quarrying" | Heavy Industry |
| "manufacturing" | Manufacturing |
| "domestic_transport" | Domestic Transport |
| "distribution" | Distribution |
| "civil_engineering" | Civil Engineering & Constructions |
| "banks_insurance" | Banks & Insurance |
| "telecom" | Telecom |
| "public_utilities" | Public Utilities |
| "security" | Security |
| "agriculture" | Agriculture |
| "rent_a_car" | Leasing & Rent-a-car |
| "it" | IT |
| "retail" | Retail |
| "wholesale" | Wholesale |
| "real_estate" | Real Estate |
| "public_administration_defense" | Public Administration & Defense |
| "science_education" | Science & Education |
| "health" | Health |
| "arts_entertainment" | Arts & Entertainment |
| "extraterritorial_organizations_bodies" | Extraterritorial Organizations & Bodies |
| "individual" | Individual |
| "other" | Other |
Vehicle Types
| Vehicle Type | Description |
|---|
| 1 | Bike |
| 2 | Bus |
| 3 | Car |
| 4 | Helicopter |
| 5 | Motorcycle |
| 6 | Personal Tracker |
| 7 | Plane |
| 8 | Ship |
| 9 | Tank |
| 10 | Tractor |
| 11 | Train |
| 12 | Tram |
| 13 | Truck |
| 14 | Van |
| 15 | Excavator |
| 16 | Armored |
| 17 | Utility |
Vehicle Map Colors
| Vehicle Map Color | Description |
|---|
| "w" | White |
| "g" | Gray |
| "y" | Yellow |
| "r" | Light Green |
| "e" | Light Red |
| "p" | Pink |
| "b" | Light Blue |
| "o" | Orange |
| "n" | Dark Green |
| "d" | Dark Red |
| "m" | Magenta |
| "l" | Dark Blue |
| "x" | Brown |
| "k" | Black |
Vehicle Map Sizes
| Vehicle Map Size | Description |
|---|
| "s" | Small |
| "n" | Normal |
| "b" | Big |
Vehicle Statuses
| Vehicle Status | Description |
|---|
| -1 | Offline |
| 0 | Engine Off |
| 1 | Engine On |
User Levels
| User Level | Description |
|---|
| 1 | Site Administrator |
| 2 | SafeFleet Administrator |
| 3 | Company Administrator |
| 4 | Department Administrator |
| 5 | Department Member |
Unit Preferences
| Unit | Description |
|---|
| 1 | Metric |
| 2 | Nautical |
| 3 | Imperial |
Event Types
| Event Type | Description |
|---|
| "impact" | Impact |
| "harsh_acceleration" | Harsh Acceleration |
| "harsh_brake" | Harsh Brake |
| "harsh_cornering" | Harsh Cornering |
| "panic" | Panic |
| "overspeeding" | Overspeeding |
| "idle" | Idling |
| "no_gps_signal" | No GPS Signal |
| "no_gsm_signal" | No GSM Signal |
| "geofence_entered" | Geofence Entered |
| "geofence_left" | Geofence Left |
| "driver_id_enable" | Driver Authentication Enabled |
| "driver_id_disable" | Driver Authentication Disabled |
| "no_driver_id" | No Driver Key |
| "imob_off" | Immobilizer Off |
| "imob_on" | Immobilizer On |
| "no_external_power" | No External Power |
| "external_power_reconnected" | External Power Reconnected |
| "low_external_battery" | Low External Battery |
| "external_battery_charging" | External Battery Charging |
| "device_sabotage" | Device Sabotage |
| "unauthorized_door_opening" | Unauthorized Door Opening |
| "unauthorized_tractor_unit_detachment" | Unauthorized Tractor Unit Detachment |
| "unauthorized_tractor_unit_attachment" | Unauthorized Tractor Unit Attachment |
| "authorized_tractor_unit_detachment" | Authorized Tractor Unit Detachment |
| "authorized_tractor_unit_attachment" | Authorized Tractor Unit Attachment |
| "gprs_traffic_enable" | GPRS Traffic Enabled |
| "gprs_traffic_disable" | GPRS Traffic Disabled |
| "overtemperature" | Overtemperature |
| "undertemperature" | Undertemperature |
| "emergency_mode" | Emergency Mode |
| "tow" | Tow |
Input IDs
| Input ID | Description |
|---|
| 1 | Door |
| 2 | Dumpster |
| 3 | Tipper |
| 4 | Pressure Pump |
| 5 | Vacuum Pump |
| 6 | Tractor Unit |
| 7 | Device Sabotage |
| 8 | Fuel Pump |
| 9 | Tank Cap |
Attribute Types
| Attribute Type | Description |
|---|
| 1 | Number |
| 2 | Boolean |
| 3 | Text |
| 4 | Date |
| 5 | Formula |
| 6 | File |
| 7 | Link |
Common Vehicle Attributes
| Attribute Name | Type |
|---|
| "Mandatory Insurance Agency" | Text |
| "Mandatory Insurance Agency Branch" | Text |
| "Mandatory Insurance Expiry Date" | Date |
| "Full Insurance Agency" | Text |
| "Full Insurance Agency Branch" | Text |
| "Full Insurance Expiry Date" | Date |
| "Vignette Expiry Date" | Date |
| "Leasing Expiry Date" | Date |
| "Technical Inspection Expiry Date" | Date |
| "Service At" | Number |
| "Last Service Date" | Date |
| "Oil Replacement At" | Number |
| "Last Oil Replacement Date" | Date |
| "Winter Tires Replacement At" | Number |
| "Last Winter Tires Replacement Date" | Date |
| "Summer Tires Replacement At" | Number |
| "Last Summer Tires Replacement Date" | Date |
| "Stationary Consumption" | Number |
| "Average Consumption" | Number |
| "Engine Displacement" | Number |
| "Power" | Number |
| "Tank Capacity" | Number |
| "Fuel Type" | Text |
| "Maximum Allowed Weight" | Number |
| "Passenger Places" | Number |
| "Category" | Text |
Fuel Types
| Fuel Type | Description |
|---|
| 1 | Gasoline |
| 2 | Diesel |
| 3 | LPG |
| 4 | Electric |
| 5 | Other |
Navigation Job States
| State | Description |
|---|
| 1 | New |
| 2 | Waiting For Execution |
| 3 | Rejected |
| 4 | Heading To |
| 5 | Executing |
| 6 | Cancelled |
| 7 | Completed |
Navigation Vehicle States
| State | Description |
|---|
| 1 | Offline |
| 2 | Unavailable |
| 3 | Available |
| 4 | Idle |
| 5 | Busy |
| 6 | Paused |
Device Settings
| Setting Name | Description | Type |
|---|
| "abs_odom_factor" | the correction factor constant for the dashboard odometer | Number |
| "abs_odom_offs" | the offset constant for the dashboard odometer | Number |
| "abs_odom_prefer" | true when the distance is computed from dashboard odometer,
false when GPS odometer is used | Boolean |
| "driver_auth" | empty string or null when driver authentication is disabled,
"*" when any supplied driver key is accepted,
driver group id when only a specific group of drivers are accepted
| String |
| "idling_threshold" | the interval after which an idling event is generated, in seconds | Number |
| "immobilizer" | the state of the immobilizer relay | Boolean |
| "overspeeding_threshold" | the speed above which an overspeeding event is generated, in km/h | Number |
| "temp1_hyst" ... "temp4_hyst" | the temperature hysteresis threshold, in ° C | Number |
| "temp1_max" ... "temp4_max" | the upper limit of the valid temperature interval, in ° C | Number |
| "temp1_min" ... "temp4_min" | the lower limit of the valid temperature interval, in ° C | Number |
| "tracking" | the tracking state | Boolean |
Ticket Statuses
| Status | Description |
|---|
| 0 | Open |
| 1 | Closed |
| 2 | Invalid |
| 3 | Accepted |
Tacho States
| State | Description |
|---|
| -1 | Absent |
| 0 | Rest |
| 1 | Available |
| 2 | Work |
| 3 | Drive |
| 4 | Unknown |
Tolling OBU Statuses
| Status | Description |
|---|
| -1 | Unknown |
| 0 | OK |
| 1 | Not Registered |
| 2 | Pending |
| 3 | Registered |
| 4 | Suspended |
| 5 | Offline |
| 6 | Other Error |
Tolling Service Statuses
| Status | Description |
|---|
| -1 | Unknown |
| 0 | OK |
| 1 | Not Registered |
| 2 | Offline |
| 3 | Other Error |
Tolling Balance Statuses
| Status | Description |
|---|
| -1 | Unknown |
| 0 | OK |
| 1 | Low |
| 2 | Empty |
- Example
The example described here fetches the list of all the vehicles accessible to the current user.
It picks one of the vehicles and obtains detailed information about it.
Then, the name and the working schedule of this vehicle are updated.
HTTP Messages
(a) The (unauthenticated) client tries to get list of vehicles. The API asks for authentication:
Client
GET /vehicles
Server
GET /safefleet/api/vehicles HTTP/1.1
Host: api.safefleet.eu
Client
403 Forbidden
Server
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"message": "authentication required"}
(b) The client authenticates. The server sends a cookie with the session id:
Client
POST /authenticate
Server
POST /safefleet/api/authenticate HTTP/1.1
Host: api.safefleet.eu
Content-Type: application/json
{"username": "test", "password": "1234"}
HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: sessionid=4ce508d20832d12a64fd49ecb336a7b6
{"message": "ok"}
(c) The client reissues the GET /vehicles request, this time with the session id cookie. The server replies with the vehicles:
Client
GET /vehicles
Server
GET /safefleet/api/vehicles HTTP/1.1
Host: api.safefleet.eu
Cookie: sessionid=4ce508d20832d12a64fd49ecb336a7b6
HTTP/1.1 200 OK
Content-Type: application/json
[
{"vehicle_id": 1234, "name": "Vehicle A", ...},
{"vehicle_id": 2345, "name": "Vehicle B", ...}
...
]
(d) The client updates the name and the working schedule of the vehicle. The server simply answers with a 204 No Content:
Client
PATCH /vehicles/{id}
Server
PATCH /safefleet/api/vehicles/1234 HTTP/1.1
Host: api.safefleet.eu
Content-Type: application/json
Cookie: sessionid=4ce508d20832d12a64fd49ecb336a7b6
{
"name": "My Vehicle",
"working_schedule": {
"mon": {
"from_minute": 0,
"to_minute": 0,
"from_hour": 8,
"to_hour": 18
},
...,
"fri": {
"from_minute": 0,
"to_minute": 0,
"from_hour": 8,
"to_hour": 18
}
}
}
Client
204 No Content
Server