API-Integration

Using our API is easy as 1,2,3 - Try it yourself!

Preamble

FLEETIZE® is offering you an API to integrate FLEETIZE-data into your 3rd-Party-Application. Our API offers you almost all data, which you also can find within our dashboards and native apps.

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 consider, 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 2.8 of 28th June 2015 and all further versions.

Content


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 a user-account at https://login.fleetize.com and own at least one FLEETIZE®-Device with a servicerate which is legited for API-Access.

Depending on the booked servicerate 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. You can find your personal API-Token at the settings-menu within your FLEETIZE®-Account, or by requesting the API with the following REST-Call:

http://track.fleetize.com/api/login/{Base64-UserID}/{Base64-Password}

Replace {UserID} and {Password} with your Base64 encrypted, personal Login-Information. The API will respond with your personal API-Token. Deposite your Token at a secure place and use it only within compiled- or server-side-code. Should you ever lose your token, please destroy your old one by generating a new personal Token in your FLEETIZE®-Account.

Successfull requests will be responded with your personal API-Token:

40bd226c754d0b98081ef62cc4ae38bd

Requesting the API

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

http://track.fleetize.com/api/{ActionCode}/{YourToken}/{Parameter1}/{Parameter2}/..

Every HTTP-Request has an Action-Code and a different amount of parameters. Some Action-Requests do not require your personal API-Token, such as the Login-Request. In all other cases please replace {YourToken} with your personal token and replace {Parameter} with the possible Action-Request-Options as described belowed. 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 (except Login-Request). 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 5 seconds from the same IP-Address. This means 12 queries per minute. If you exceed this limit, you will get the following warning and the 5 second counter will restart:

ERROR #1001 - QUERY-THRESHOLD EXCEEDED

The API-Access will be temporary locked in case of continuous requests lower than 5 seconds and you will be punished to wait at least 24 hours before you can use the API again. In this case you will see this warning:

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:

http://track.fleetize.com/api/deviceshort/{YourToken}

Please replace {YourToken} with your personal token. 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- & Route-Information

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

http://track.fleetize.com/api/device/{YourToken}/{VehicleApiID}/{OptionalTimestamp}

Please replace {YourToken} with your personal token, replace "VehicleApiID" with the API-ID of the intended vehicle and replace "OptionalTimestamp" with an optional UNIX-Timestamp of the targeted day. You can find the Vehicle-API-ID within the list of your devices or within the respective vehicle-configuration in your FLEETIZE®-Account.

Giving a Timestamp is optionally. If you don't add a Timestamp, the API will export the latest data for the requested vehicle. 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 would convert the Timestamp 1416567600 to 1416528000 so it always returns the vehicle-data of the whole 24 hours of the day.

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;...",
  }
 ]
}

API-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 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_roaming_d
Current national-roaming-state, Boolean
device_roaming_i
Current international-roaming-state, Boolean
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
OBD2-Vault-Code, if present
error_text
OBD2-Vault-Code-description, if present
status_text
Current device-state, as text
location
Current device-geo-location

Node "routes"

Every route-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

Get the full API-Documentation



This is just a small insight into our API. Please contact the customecare for more:

Contact