Introducing the MyGeotab API Adapter

Introduction

Streaming of data from the MyGeotab platform into external systems via the Geotab API is accomplished using the data feed — a lightweight and highly-scalable incremental polling mechanism. Building a full-scale integration typically involves utilizing numerous data feeds to pull various types of data from a MyGeotab database. There are many complexities inherent in developing a solid integration.

The MyGeotab API Adapter solution serves as both an example of proper integration via data feeds and the potential foundation for those seeking to develop new integrations with the Geotab platform. Essentially, it uses data feeds to pull the most common datasets from a MyGeotab database and stream the data into tables within a PostgreSQL, SQL Server or SQLite database. This could account for half the work in terms of a unidirectional integration where the data from the database is further processed for integration into an external system. And, since the MyGeotab API Adapter solution is available and open source on GitHub, it can be used as-is, or modified as necessary to meet specific requirements.

This post describes the architecture of the MyGeotab API Adapter and explains how it works.

See also: Using the MyGeotab python API to create custom reports

How the MyGeotab API Adapter is structured

The source application was created using Microsoft's C# and the latest platform-independent .Net Core implementation of the Microsoft Framework. The beauty of this is that it allows the published solution to be deployed to a number of different environments including Windows, Linux and even macOS.

In order to write to and get data from the local database, a simple Object-Relational Mapper (ORM) named Dapper was employed. The solution was designed using a layered architecture in which data access code is separated from business logic, thereby providing the ability to support multiple database types with a single code base. Currently, the application supports the PostgreSQL and SQLite database formats natively. Adding support for an additional database type is a relatively trivial exercise, provided that there is a .NET Core data provider for the subject database type.

The MyGeotab API Adapter uses the Geotab API to write to or retrieve data from the relevant MyGeotab database instance(s).

See also: Empowering business with data intelligence: Fiona Zhao interview

How it works

To get to a point where you are able to access a local database populated with data extracted from a MyGeotab database, the following steps will need to be executed:

1. Obtain permission from the owner of the MyGeotab database from which data is to be extracted. Typically this occurs as part of a business case for integration with an external (to Geotab) system.
2. Obtain user credentials for the MyGeotab database. It is recommended that the MyGeotab API Adapter be configured to use a service account for MyGeotab access. See Service Account Guidelines for more information.
3. Download the MyGeotab API Adapter source code or pre-published release package (see the MyGeotab API Adapter - Solution and Implementation Guide for configuration and deployment instructions).
4. Ensure that the destination adapter database has been set-up and that it is accessible from wherever the adapter solution will be run (e.g. there may be some networking or firewall considerations if the adapter and its associated database are installed on different servers).
5. Make the necessary changes to the appsettings.json file.
6. When deploying the MyGeotab API Adapter solution, configure the adapter to be run as a service - for example, by setting-up a Scheduled Task on a Windows server - and then start it.

Assuming the above steps have been completed correctly, the application will start populating the local database based on the configured options. From here, it is possible to integrate the data with other systems by virtually any means imaginable.

Within the context of a unidirectional integration where data from the database is further processed for integration into an external system, utilization of the MyGeotab API Adapter might mean that half the work is already done from the start. 

Furthermore, since the MyGeotab API Adapter source code is freely-available on GitHub, it is possible to modify the solution as required to meet specific needs.

Types of data that can be retrieved

Some of the data that can be retrieved using the MyGeotab API Adapter is as follows:

Reference Data (data that changes infrequently or that is static in nature - generally user-added data):

• Users — Users of the MyGeotab system. A user can be a MyGeotab user or a user that is a Driver.
• Devices — A device represents the physical tracking device installed in the vehicle. A device and vehicle is typically synonymous since the GO tracking device is installed in a vehicle.
• Zones — Sometimes referred to as a "Geofence", a zone is a virtual geographic boundary, defined by its points representing a real-world geographic area.
• Rules — A rule is the definition of conditions that, when "violated," will generate an Exception Event. The rule's logic is defined by its tree of Condition(s). It's condition tree will be evaluated against data for device(s) that are members of the rule's assigned group(s) or the device(s)/driver(s) defined in the rule condition tree. The conditions will be evaluated independently against the assets in the selected groups.
• Diagnostics — Vehicle diagnostic information from the engine computer that can either be measurement data or fault code data.

Feed Data (generally consists of data points collected from vehicles via a Geotab GO or other devices and streamed from the MyGeotab database using data feeds.)

• LogRecords — A LogRecord is an entry containing data for a device's position and speed at a specific date and time.
• StatusData — A StatusData record represents an engine status record from the engine system of the specific Device.
• FaultData — A FaultData record represents a fault code record from the engine system of the specific Device.
• Exception Events — ExceptionEvents are generated by Rule violations.
• Trips — A Trip record represents a vehicle’s trip and a summary of the driving activity during that trip. A complete "trip" is defined as starting at the time at which the vehicle starts and begins being driven. The trip continues after the vehicle has been stopped and ends at the time the vehicle restarts and begins being driven again; this  starts the next trip.
• DVIRLogs — A DVIRLog is a Driver Vehicle Inspection Report which is prepared by a driver regarding defects in parts of a vehicle associated with a Device or Trailer. Once the report is completed with optional driver remarks, the DVIR log will be acted upon, and marked as repairs made or not necessary (usually by another User). The driver then will mark the log as certified for being safe or unsafe to operate based on the effectiveness of any repairs made or comments for repairs not performed.

Note: The amount and detail of data you will be able to view is related to your rate plan.

Conclusion

The MyGeotab API Adapter solution serves as both an example of proper integration via data feeds and the potential foundation for those seeking to develop new integrations with the Geotab platform. For more information, please refer to the associated documentation: MyGeotab API Adapter - Solution and Implementation Guide.

Contributor: Stephen Dietz, Solutions Engineering, Geotab