Here's example of how to use Api/Report commands.
Main principle is illustrated here:
Let's suppose we need to call fuel report, what must be grouped via vehicles. We need to know report ID, parameters, and groupable columns.
1. Ask for report ID
We use listReports
command to get available reports.
app.ecofleet.com/seeme/Api/Reports/listReports?key=apidemo-NJ8V7PENgkau5FYH
Response:
XML:
<?xml version="1.0" encoding="utf-8" ?>
<nodes>
<status>0</status>
<response>
<node key="0">
<id>NewDayReport</id>
<title>Day report</title>
</node>
<node key="1">
<id>NewPeriodReport</id>
<title>Period report</title>
</node>
<node key="2">
<id>booking</id>
<title>Booking report</title>
</node>
</response>
</nodes>
JSON:
{
"status":0,
"response":[{
"id":"NewDayReport",
"title":"Day report"
},{
"id":"NewPeriodReport",
"title":"Period report"
},{
"id":"booking",
"title":"Booking report"
}]
}
Here we get to know, that id of fuel report is fuel
.
2. Ask for report configuration
There is getReportConf
command, what uses id value taken from listReports
:
app.ecofleet.com/seeme/Api/Reports/getReportConf?id=fuel&key=apidemo-NJ8V7PENgkau5FYH
Simplified response (cleaned empty or null elements):
XML:
<?xml version="1.0" encoding="utf-8" ?>
<nodes>
<status>0</status>
<response>
<id>fuel</id>
<title>Fuel report</title>
<parameters>
<node key="0">
<name>begTimestamp</name>
<type>date</type>
<allowNull>1</allowNull>
</node>
<node key="1">
<name>endTimestamp</name>
<type>date</type>
<allowNull>1</allowNull>
</node>
<node key="2">
<name>objectIds</name>
<type>array_of_int</type>
<allowNull>1</allowNull>
</node>
<node key="3">
<name>groupBy</name>
<type>string</type>
<allowNull>1</allowNull>
</node>
<node key="4">
<name>sortBy</name>
<type>string</type>
<allowNull>1</allowNull>
</node>
<node key="5">
<name>sortDir</name>
<type>string</type>
<allowNull>1</allowNull>
</node>
</parameters>
<outputType>
</outputType>
<output>
<node key="0">
<title>Vehicle</title>
<type>string</type>
<data>objectName</data>
<groupBy>1</groupBy>
</node>
<node key="1">
<title>Date</title>
<type>date</type>
<format>d.m.Y</format>
<data>date</data>
<groupBy>1</groupBy>
</node>
<node key="2">
<title>Time</title>
<type>date</type>
<format>H:i</format>
<data>time</data>
</node>
<node key="3">
<title>Location</title>
<type>string</type>
<data>location</data>
</node>
<node key="4">
<title>Before</title>
<type>integer</type>
<data>fuelBefore</data>
<unit>l</unit>
</node>
<node key="5">
<title>Refueled</title>
<type>integer</type>
<data>fuelAdded</data>
<unit>l</unit>
<summaryType>sum</summaryType>
</node>
<node key="6">
<title>After</title>
<type>integer</type>
<data>fuelAfter</data>
<unit>l</unit>
</node>
<node key="7">
<title>Driver</title>
<type>string</type>
<data>driverName</data>
</node>
</output>
</response>
</nodes>
JSON:
{
"status":0,
"response":{
"id":"fuel",
"title":"Fuel report",
"parameters":[{
"name":"begTimestamp",
"type":"date",
"allowNull":true
},{
"name":"endTimestamp",
"type":"date",
"allowNull":true
},{
"name":"objectIds",
"type":"array_of_int",
"allowNull":true
},{
"name":"groupBy",
"type":"string",
"allowNull":true
},{
"name":"sortBy",
"type":"string",
"allowNull":true
},{
"name":"sortDir",
"type":"string",
"allowNull":true
}],
"outputType":null,
"output":[{
"title":"Vehicle",
"type":"string",
"data":"objectName",
"groupBy":true,
"default":false,
"description":"",
"filterBy":false
},{
"title":"Date",
"type":"date",
"format":"d.m.Y",
"data":"date",
"groupBy":true,
"default":false,
"description":"",
"filterBy":false
},{
"title":"Time",
"type":"date",
"format":"H:i",
"data":"time",
"default":false,
"description":"",
"filterBy":false
},{
"title":"Location",
"type":"string",
"data":"location",
"default":false,
"description":"",
"filterBy":false
},{
"title":"Before",
"type":"integer",
"data":"fuelBefore",
"unit":"l",
"default":false,
"description":"",
"filterBy":false
},{
"title":"Refueled",
"type":"integer",
"data":"fuelAdded",
"unit":"l",
"default":false,
"summaryType":"sum",
"description":"",
"filterBy":false
},{
"title":"After",
"type":"integer",
"data":"fuelAfter",
"unit":"l",
"default":false,
"description":"",
"filterBy":false
},{
"title":"Driver",
"type":"string",
"data":"driverName",
"default":false,
"description":"",
"filterBy":false
}]
}
}
Based on parameters part, fuel report call would look like this:
fuel([date begTimestamp], [date endTimestamp], [int[] objectIds],
[string groupBy], [string sortBy], [string sortDir])
All non-mandatory parameters are in brackets, and there is field type before parameter name.
Summary of report fields would look like:
title | type | data | unit | groupBy | format | summaryType |
---|---|---|---|---|---|---|
Vehicle | string | objectName | 1 | |||
Date | date | date | 1 | d.m.Y | ||
Time | date | time | H:i | |||
Location | string | location | ||||
Before | integer | fuelBefore | l | |||
Refueled | integer | fuelAdded | l | sum | ||
After | integer | fuelAfter | l | |||
Driver | string | driverName |
Note that objectName
and date
columns are groupable.
3. Ask report
Now put all pieces together and build report query. We would like to use following parameters:
begTimestamp | 2019-10-01 |
endTimestamp | 2019-10-31 |
objectIds | all vehicles |
groupBy | date |
sortBy | don't specify |
sortDir | don't specify |
Remember that additionally to those parameters, we have to use id for report identificator, and format, if needed.
Query:
Api/Reports/getReport?id=fuel&
begTimestamp=2019-10-01&
endTimestamp=2019-10-31&
groupBy=date&
format=xml&
key=yourApiKey
Possible response:
XML:
<?xml version="1.0" encoding="utf-8" ?>
<nodes>
<status>0</status>
<response>
<data>
<node key="0">
<date>2019-10-04</date>
<time>08:31:32</time>
<timestamp>2019-10-04 08:31:32</timestamp>
<objectId>157423</objectId>
<objectName>123ABC</objectName>
<location>Raudtee 2a, Nõo alevik, Nõo vald, Tartumaa, EE</location>
<fuelBefore>19</fuelBefore>
<fuelAdded>41</fuelAdded>
<fuelAfter>60</fuelAfter>
<driverName>Markus Sucher</driverName>
</node>
<node key="1">
<date>2019-10-10</date>
<time>08:35:29</time>
<timestamp>2019-10-10 08:35:29</timestamp>
<objectId>157423</objectId>
<objectName>123ABC</objectName>
<location>Raudtee 2a, Nõo alevik, Nõo vald, Tartumaa, EE</location>
<fuelBefore>17</fuelBefore>
<fuelAdded>51</fuelAdded>
<fuelAfter>68</fuelAfter>
<driverName>Markus Sucher</driverName>
</node>
<node key="2">
<date>2019-10-18</date>
<time>08:37:53</time>
<timestamp>2019-10-18 08:37:53</timestamp>
<objectId>157423</objectId>
<objectName>123ABC</objectName>
<location>Raudtee 2a, Nõo alevik, Nõo vald, Tartumaa, EE</location>
<fuelBefore>17</fuelBefore>
<fuelAdded>50</fuelAdded>
<fuelAfter>67</fuelAfter>
<driverName>Markus Sucher</driverName>
</node>
</data>
<title>Fuel report 01.10.2019-23.10.2019</title>
</response>
</nodes>
JSON:
{
"status":0,
"response":{
"data":[{
"date":"2019-10-04",
"time":"08:31:32",
"timestamp":"2019-10-04 08:31:32",
"objectId":"157423",
"objectName":"123ABC",
"location":"Raudtee 2a, Nõo alevik, Nõo vald, Tartumaa, EE",
"fuelBefore":19,
"fuelAdded":41,
"fuelAfter":60,
"driverName":"Markus Sucher"
},{
"date":"2019-10-10",
"time":"08:35:29",
"timestamp":"2019-10-10 08:35:29",
"objectId":"157423",
"objectName":"123ABC",
"location":"Raudtee 2a, Nõo alevik, Nõo vald, Tartumaa, EE",
"fuelBefore":17,
"fuelAdded":51,
"fuelAfter":68,
"driverName":"Markus Sucher"
},{
"date":"2019-10-18",
"time":"08:37:53",
"timestamp":"2019-10-18 08:37:53",
"objectId":"157423",
"objectName":"359TNJ",
"location":"Raudtee 2a, Nõo alevik, Nõo vald, Tartumaa, EE",
"fuelBefore":17,
"fuelAdded":50,
"fuelAfter":67,
"driverName":"Markus Sucher"
}],
"title":"Fuel report 01.10.2019-23.10.2019"
}
}