API / FLEETIZE

Preamble

FLEETIZE® is offering you an API to integrate FLEETIZE-rawdata into your 3rd-Party-Application. Our API offers almost all rawdata, also used for FLEETIZE-Functions.

This API makes it easy to build your own vehicle-fleet-processes. Use it to automate your daily dues according to the states and locations of your vehicles and safe time and reduce your costs. Please mind, that this API only delivers rawdata and does not contain processed results like logbook-route-data eg. Also mind, that this document doesnt represents the full list of all API-Commands. In cases you want to do more, please do not hesitate to contact us.

Note: this API-Documentation describes the API starting from FLEETIZE®-Dashboard-Release Version 3.4.49 of 31st January 2021 and all further versions.

Content

Intended Audience
Requirements
Getting your API-Token
Essential Notes for API-Usage
Requesting the API
API-Restrictions
Getting a list of your devices
Getting specific Device- & Route-Information
Tags-Reference

Intended Audience

This documentation helps software developers who want to integrate FLEETIZE® within 3rd-Party applications. Use this API to pump out vehicle-data from the FLEETIZE®-Platform for using these in your own application or projects. To start using our API, we recommend to cover the following knowledge:

Usage of HTTP protocol
Experiences in using RESTful web services
Your favorite Programming-language for parsing JSON-Files

Requirements

For using the FLEETIZE®-API you need to register for an user-account at https://login.fleetize.com and own at least one FLEETIZE®-Device with a service-rate which is legited for API-Access.

Depending on your service-rate the amount of accessable information can vary.

Getting your API-Token

To avoid misuse of the FLEETIZE®-API, every legitimated user needs to use his own personal API-Token. As far as you are legitimated to use the API, you can find your personal API-Token within your FLEETIZE®-Account at the settings-menu under "My Account > Administration".

Essential notes for the API-Usage

UNIX-Timestamps

You will have to provide or receive Unix-Timestamps while using the API. Those are always GMT-Based without any timeshifting. You will need to implement any calculation inside your application to get the correct Time-Format for your purposes.

Requesting the API

Our API can be accessed with simple HTTP-Request REST-Calls, according to the following URI-Structure (Uniform Resource Identifiers):

https://api.fleetize.com/v2/{ActionCode}

Every HTTP-Request has an Action-Code and a different amount of POST-Parameters. Every Action-Request require your personal API-Token. Please mind the API-Restrictions about how to use your personal API-Token correctly.

In all cases requesting the API you will get a JSON-File as a result, containing data of the requested Action-Code.

API-Restrictions

For requesting the API, each request needs to contain your personal API-Token. Without this Token, or by providing a wrong API-Token, you will get the following warning while accessing the API:

ERROR #1000 - INVALID API TOKEN

API-Requests per minute

Depending on your payed rate, you are allowed to request API every 60 seconds from the same IP-Address. If you exceed this limit, you will get the following warning and the 60 seconds counter will restart:

ERROR #1055 - QUERY-THRESHOLD EXCEEDED - PLEASE REDUCE QUERY-INTERVAL, OTHERWISE YOUR TOKEN WILL BE BLOCKED

The API-Access will be blocked in case of continuous requests lower than 60 seconds. In this case you will see this warning and have to contact the FLEETIZE-Support:

ERROR #1002 - QUERY-THRESHOLD EXCEEDED - API TOKEN BLOCKED

IP-Limitation

Each API-Request is paired with the calling IP-Address. Depending on your payed rate, you can access the API only with one IP-Address at the same time. Each request is logged and any abuse of the API may result in a temporary or permanent ban from the API.

Getting a list of your devices

Returning all legitimated devices for the given API-Token is possible with the following Action-Request:

https://api.fleetize.com/v2/devicelist

POST-Parameters:

Attribute

Description

apitoken

Your personal API-Token

scope

You can reduce the amount of data by specifying them, eg. "device_id;device_name;"

activity_after

Filter to those vehicles, which had any activity after this unix-timestamp

Filtering the results with scope and activity_after will decrease the amount of data and increase the response time. Especially on a large amount of queryied vehicles, this can prevent to reach api-limitations due to a large amount of data within a period of time.

For scoping the data with scope please provide the needed variable-names separated by semicolons.

The API will respond with all of your legitimated devices including the basic device-data:

[
  {
   "device_id":492,
   "device_imei":359183064907632,
   "device_type":"CAR",
   "device_name":"My vehicle",
   "device_description":"BMW E46 M3 Coupe",
   "device_portrait":"http%3A%2F%2Ftrack.fleetize.com%2Fassets%2Fimg%2Fdevices%2F1471424858072.png",,
   "device_mileage":277910,
   "device_distance":0,
   "online_timestamp":1426576180,
   "heartbeat_timestamp":1426776180,
   "error_code":0,
   "error_text":null,
   "status_absence":"Parking: 1d 10h",
   "status_description":"parked since Di, 17.03., 08:09",
   "status_text":"offline",
   "location":"48.87778,9.34889",
  },
  {
   "device_id":493,
   "device_imei":349133054916622,
   "device_type":"CAR",
   ...
  }
]

Getting specific Device- & Tracking-Information

You can get all device-data and tracking-information by sending the following Action-Request:

https://api.fleetize.com/v2/device

POST-Parameters:

Attribute

Description

apitoken

Your personal API-Token

device

Device-API-ID of the intended vehicle

time

Optional unix-timestamp of targeted day. Leave empty to get data of latest, activity day.

scope

You can reduce the amount of data by specifying them, eg. "device_id;device_name;"

You can find the Vehicle-API-ID within the list of your devices or within the respective vehicle-configuration-page in your FLEETIZE®-Account.

Giving a Timestamp is optionally. If you don't serve a timestamp, the API will export the latest data for the requested device. For Example: for exporting data of the 21st November 2014, please add the Timestamp "1416528000". You also can give the timestamp for 21st November 2014, 11 AM. The API will convert it to 1416528000 so it always returns the vehicle-data of the whole 24 hours of the day.

Scoping the data with "scope" will help you to reduce the transfer data, if you are only interested in partial information. Please provide the needed variable-names separated by semicolons.

In all cases requesting the API you will get a JSON-File as a result, containing all relevant data of the last 24 hours for the given vehicle-id:

{
"device":
  {
   "device_id":492,
   "device_name":"My vehicle",
   "device_description":"BMW E46 M3 Coupe",
   "device_mileage":277910,
   "status_text":"offline",
   "location":"48.87778,9.34889",
  },
"routes":[
  {
   "origin_timestamp":"1428498484",
   "origin_mileage":277843,
   "origin_location":"48.87917,9.19194",
   "destination_timestamp":"1428503164",
   "destination_mileage":277870,
   "destination_location":"48.82556,9.33111",
   "route_points":"48.82556,9.33111,0;48.82556,9.33111,0;...",
  }
]
}

Tags-Reference

Node "device"

Within every API-Request, a JSON-File will be delivered containing the latest vehicle sensor- und location- information in the Parent-Node. The contained Tags are:

Attribute

Description

timestamp

Beginning of output-data, as unix-timestamp

device_id

API-ID of device

device_imei

Device-IMEI

device_type

Type of device

device_name

Name of device, defined by owner

device_description

Description of device, defined by owner

device_mileage

Current FLEETIZE-mileage of device, in kilometers

device_mileage_raw

Current internal mileage of device, in kilometers

device_distance

Day-trip-counter of device, in kilometers

device_portrait

Raw-URL-Encoded path of the image-file

device_speed

Current speed of engine, in km/h

device_upm

Current rounds-per-minute of engine, in r/m

device_temp_engine

Current engine-temperature, in Celsius

device_voltage_external

Current voltage of vehicle-battery, in Volt

device_voltage_internal

Current voltage of device-battery, in Volt

device_angle

Current perspective of device, in degree

online_timestamp

Last Activity-time of device, as unix-timestamp

heartbeat_timestamp

Last Contact to device, as unix-timestamp

error_code

Device-Vault-Code, if present

error_code_time

Time when Device-Vault-Code occured, as unix-timestamp

error_text

device-Vault-Code-description, if present

status_text

Current device-state, as text

status_code

Current device-state, as code

location

Current device-geo-location

Node "routes"

Every tracking-information such as starting and ending time, as well as routepoints are found within this node. The contained Tags are:

Attribute

Description

route_points

Contains all route-points semicolon-seperated: GPS-Latitude,GPS-Longitude,Device-Speed; GPS-Latitude,GPS-Longitude,Device-Speed;â€¦

origin_timestamp

Time while leaving origin, as unix-timestamp

origin_mileage

Mileage while leaving origin, as kilometers

origin_location

Geo-Location while leaving origin

destination_timestamp

Time while reaching destination, as unix-timestamp

destination_mileage

Mileage while reaching destination, as kilometers

destination_location

Geo-Location while reaching destination

average_speed

Average speed of current route while driving (Sum of all speed-packages divided by total packge-amount, null-speed-values are extracted)

average_speed_distance

Average speed of current route while driving (relation between time and distance of the current route)

pause_duration

Duration of all pause in seconds

Node "route_pause"

Within the Node "routes" you will find this node, containing all pause-activities. The contained Tags are:

Attribute

Description

grouped

If there are more than one pause-activities in this area, then value is 1

type

pause-activity-type: 1 = Ignition OFF, 2 = Long-Stopped

start_timestamp

Beginning of pause-activity, as unix-timestamp

end_timestamp

Ending of pause-activity, as unix-timestamp

mileage

Mileage while pause-activity, in kilometers

location

Geo-Location while pause-activity

Attribute "status_code"

Sometimes you will find an attribute called status_code which will define the current state of the specific device:

Code

Description

Offline: Device is parked or in sleeping-mode

Active: Device is active and

Inactive: Device is active but not moving

Not moved yet: Device has no exact status yet

Unused

Attribue "error_code"

There will be Error-Codes delivered within the attribute error_code which will give you more details about what occured:

Code

Description

No Error occured

Modified: Device was plugged-out and plugged-in again

Unplugged: Device is currently unplugged

No Signal: Device is currently not connected

No GPS: Device has no GPS-Signal

Bad GPS: Device has bad GPS-Signal

Need further features?

For special requirements please contact the customecare for more:

Contact

Die FLEETIZE Fuhrpark-Experten beraten Sie gerne

Anfrage wird verschickt

Bitte haben Sie einen Moment Geduld...

Vielen Dank!

API-Integration

Preamble

Content

Intended Audience

Requirements

Getting your API-Token

Essential notes for the API-Usage

UNIX-Timestamps

Requesting the API

API-Restrictions

API-Requests per minute

IP-Limitation

Getting a list of your devices

Getting specific Device- & Tracking-Information

Tags-Reference

Node "device"

Node "routes"

Node "route_pause"

Attribute "status_code"

Attribue "error_code"

Need further features?