Skip to main content
Sign in

Report-management

Marisa Potgieter
  • Updated

Api Reports

Reports management

Reports API consists of 3 functions:

  • Api/Reports/listReports - get ID-s of your reports
  • Api/Reports/getReportConf - get report details: supported parameters, parameter formatting, other formatting options available
  • Api/Reports/getReport - get actual report data

Prerequisites

  • Organization has reports module enabled
  • API user  - user role must have permission granted to access reports module as well as individual reports.

Api/Reports/listReports

Body of the request does not require additional parameters

Example API call: app.ecofleet.com/seeme/Api/Reports/listReports?key=API_KEY

Response XML:

    0                         NewDayReport -- unique report ID (to be used  as parameter  in getConfReport call )             Day report -- report name in language, which is set in API user preferences                             newTasksReport             Tasks report             -- element is ONLY visible for User Defined reports                                     9b7a907f-3f90-412c-9abf-93f28fad385c -- stateId value for getReport                     User defined report -- name of custom report                                                         booking             Booking report                

Response JSON:

{ "status":0, "response":{   "NewDayReport":{     "id":"NewDayReport",     "title":"Day report"   },   "NewPeriodReport":{     "id":" newTasksReport",     "title":"Period report",     "states":[{         "id":”9b7a907f-3f90-412c-9abf-93f28fad385c”,         "title":" User defined report "       }]

},   "booking":{     "id":"booking",     "title":"Booking report"   } } }

Troubleshooting

Here are solutions for some problems.

  • Error message "no permission": there is no reports module assigned to API user. Please add it via roles. If your organization does not have reports module, ask it via sales manager or technical support.
  • empty response: there are no reports module shared out to API user via roles.
  • your report is not listed: share out that particular report to API user via roles. If some report is still not available, it may be not enabled for your organization. Please contact your sales representative or customer support.

Api/Reports/getReportConf

Body of the request requires ID parameter that can be taken from getReports … node

Example API call:

app.ecofleet.com/seeme/Api/Reports/getReportConf?id=newTasksReport&proto=&key=API_KEY

Response XML:

    0                 newTasksReport         Tasks report                                     begTimestamp                 date                 Y-m-d                                                                                                                                 1                                                                             …                                                     ID                 string                                                 taskId                                                                                                                                                 Task id                                                                        

Parameters section

This is a list of  elements, that lists available parameters forgetReport , like period begin and end timestamp, list of objects, groupable column etc.

Parameteres have following elements:

  • name - parameter name, or identificator. This is what you use in getReport command
  • type - type of value for parameter. Some of the possible values:
  • integer - numbers 0-9
  • array_of_int: comma-separated list of integers
  • datetime, date, dateortime: parameter must contain date or time. Exact format is shown in format element
  • object: rarely used
  • string: any text
  • format - how parameter should be formatted. Usually use datetime parameters. Possible values may be: Y-m-d 00:00:00, Y-m, Y-m-d H:i:s etc.
  • allowNull - if nonzero, this parameter is not mandatory, meaning parameter can be skipped
  • defaultValue - if this parameter is not included, default value is used instead
  • displayFormat, includeNullOption - purpose not known
  • allowTags, inputFormat, map, validate, value - currently not in use

Output section

Contains columns, that are available for the report, and includes detailed formatting information.

  • data - unique ID of that column
  • title - human-readable name for that column, in localized language of API user

  • type – type of data in column

  • boolean - 0 or 1

  • data - used very rarely
  • date - contains date without time
  • datetime - contains date and time value
  • decimal - float number with digits
  • float - same as decimal, but comes with format parameter, what usually shows, how many digits are after comma
  • integer - numbers 0-9
  • interval - time value indicating, how long some period lasted. Not same as date and time
  • mixed - rarely used
  • string - any text
  • time - contains only time

  • format - how column is formatted.

  • for date and time types, it shows, how output is composed, like Y-m-d H:i:s

  • for float type, there is number, what shows the number digits after decimal
  • default - if not selected into column list, this column is added to report by default
  • description – description of data in the column
  • filterBy - it is possible to filter data using that column
  • hide - default, this column is hidden
  • showZeros - if value of the column is zero, it's not hidden, but shown as zero

  • summaryType - how the column is summarized. There are multiple  possibilities, but there are some main choices:

  • sum - adding numbers

  • max - finding largest from values
  • nonNullAverage - used mostly for fuel calculations. Calculates average from only those values, that are filled
  • weightedAvg - weighted arithmetic mean. This averaging method uses one other column "weight". The larger weight value - the more this value gives to end result.
  • refuelingDifferenceAvg, fuelPer100, fuelPerHour, estFuelCost, relationBetweenSums - not covered in that manual
  • unit – unit type
  • decimalSeparator - which character is used as decimal. This comes from language preferences of API user.
  • align – shows how data is aligned in report. Possible values alignL and alignR
  • check - what to check for that column. This is marker for report generator
  • dataOnly, sortData - purpose not known
  • thousandSeparator - not in use

Troubleshooting

You may meet following errors:

  • Error 7 "no permissions": API user does not have reports module
  • Error 8 "No rights for this report": API user does not have access to this report, or such report does not exist. Or id parameter is empty. Make sure that id value is listed in listReports command.

Api/Reports/GetReports

Body of the request requires parameters obtained from getReportConf

  • ID
  • BegTimestamp
  • EndTimestamp
  • objectIds all vehicles  (if applicable)
  • groupBy date
  • sortBy don't specify
  • sortDir don't specify

Example API call:

app.ecofleet.com/seeme/Api/Reports/getReport?key=API_KEY&id=newTasksReport&begTimeStamp=2024-04-18&endTimeStamp=2024-04-18&format=XML&stateID=9b7a907f-3f90-412c-9abf-93f28fad385c

Response XML:

    0                 Tasks report 18.04.2024                    

20720307 3778457 Ksenia Test new task snow_removal Priisle tee 16, 13914 Tallinn, Estonia This is new test task 2024-04-18 10:51:00 2024-04-18 10:51:00 2024-04-18 10:51:00 20720307 2024-04-18 10:51:53 2024-04-18 10:51:53 TODO 2024-04-18 10:51:53 59.450935 24.893814 16600532 fitness 24/7 112 146 0 Estonia Harju County 13914 Priisle tee 16 Tallinn City Priisle tee 16, 13914 Tallinn, 59.450935 24.893814 <6489-26284>water</6489-26284> water

     

Powered by Zendesk