Articles in this section

Example

Teet Kalm
  • Updated
Follow

Here's example of how to use Api/Report commands.

Main principle is illustrated here:

api_reports_overview_state_en.png

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"
}
}

 

Related articles

Comments

0 comments

Please sign in to leave a comment.