Integration Guide
0 mins to read
Geotab Data-Only Plan API (.NET): Developer Guide
Integration Guide
0 mins to read
Learn more about the Geotab Data-Only Plan API, which provides a wrapper around the MyGeotab .NET API and exposes methods and encapsulates business rules such that data-only integrators can easily work with the MyGeotab API within the constraints imposed by the data-only option.
Developer Guide
Latest Update: 2021-05-20
Table of Contents
Overview
Integrators wishing only to extract device, engine and IOX data from Geotab may opt for API-only plans that do not include the use of the MyGeotab interface. Furthermore, with API-only plans, the usage of the MyGeotab API is greatly restricted; many calls are disallowed, including those related to map provider services (including geocoding), posted road speed look up, exception rules or exception events, zones, routes, text messaging, notifications, and any other API calls not specifically listed as available in the API calls available by Rate Plan, Geotab Platform Partner v1.0 [PUBLIC] document. These restrictions may present challenges for integrators working with the MyGeotab SDK. This is where the Geotab Data-Only Plan API comes in.
Although not an official Geotab product, the Geotab Data-Only Plan API provides a wrapper around the MyGeotab .NET API, exposing methods and encapsulating business rules such that Data-only integrators can easily work with the MyGeotab API within the constraints imposed by the Data-only option. In addition, an example solution is available to demonstrate usage of the Geotab Data-Only Plan API. This document provides information related to both the Geotab Data-Only Plan API and the associated example solution.
Geotab Data-Only Plan API
The Geotab Data-Only Plan API is available as a NuGet package for use in Visual Studio. A Google Slides presentation, Geotab Data-Only Plan API [PUBLIC], provides supporting documentation and is referenced herein.
Prerequisites
The Geotab Data-Only Plan API requires:
- .NET 5.0 SDK (https://dotnet.microsoft.com/download) or higher;
- Geotab.Checkmate.ObjectModel (included with the NuGet package); and
- Ideally, MyAdmin credentials with the MyAdminApiUser and Device_Admin roles. These roles should be used when authenticating in order to be able to take advantage of all available methods; MyGeotab credentials may be used, but then the CreateDatabaseAsync() method cannot be used.
API Reference
Under the hood, the Geotab Data-Only Plan API utilizes the Geotab.Checkmate.ObjectModel and all calls are routed through the MyGeotab .NET API. As such, the MyGeotab API Reference page may be used for object reference.
Based on the API calls available by Rate Plan, Geotab Platform Partner v1.0 [PUBLIC] document, methods and objects available for API-only integrators are summarized on this slide. Whereas the MyGeotab API is structured to have a small number of methods that operate with numerous object types, the Geotab Data-Only Plan API breaks these out into individual methods that are parameterized appropriately based on the allowed methods, objects and parameters — as highlighted on this slide.
Methods available in the Geotab Data-Only Plan API are shown on this slide. Blue text denotes MyGeotab API objects associated with the subject methods. Shading of the cells in the table helps to relate Geotab Data-Only Plan API methods back to associated methods in the MyGeotab API as follows:
Cell Colour & MyGeotab API Method | Geotab Data-Only Plan API Method Description |
Add(...) | Use the MyGeotab API Add(...) method. |
Get(...) | Use the MyGeotab API Get(...) method. |
GetCountOf(...) | Use the MyGeotab API GetCountOf(...) method. |
GetFeed(...) | Use the MyGeotab API GetFeed(...) method. |
Remove(...) | Use the MyGeotab API Remove(...) method. |
Set(...) | Use the MyGeotab API Set(...) method. |
Pass-through | Methods in cells with no shading represent “pass-through” methods that execute MyGeotab API methods bearing the same names. These are included to allow full API-only access through the Geotab Data-Only Plan API alone. The only exception is the ArchiveDeviceAsync() method, which was added to allow for “unplugging” devices while avoiding doing so accidentally if the capability were to be included in the SetDeviceAsync() method. |
Geotab Data-Only Plan API Examples
The Geotab Data-Only Plan API Examples solution is a Visual Studio solution that demonstrates usage of the Geotab Data-Only Plan API. It is comprised of two projects — each of which is a .NET Core C# console application:
Project | Description |
Geotab.DataOnlyPlan.API.Examples |
|
Geotab.DataOnlyPlan.API.Examples.FleetMonitor |
|
Prerequisites
Prerequisites for the Geotab Data-Only Plan API Examples solution are the same as those of the Geotab Data-Only Plan API.
Getting Started
The Geotab Data-Only Plan API Examples solution can be obtained by cloning the Git repository. Once downloaded, open the solution — Geotab Data-Only Plan API Examples.sln — using Microsoft Visual Studio or Visual Studio Code.
Geotab.DataOnlyPlan.API.Examples
The Geotab.DataOnlyPlan.API.Examples project contains basic implementation examples for the methods available in the Geotab Data-Only Plan API.
On start-up, a console window is displayed prompting the user to enter a MyGeotab server and database to run against, along with MyGeotab credentials. Upon successful authentication using these supplied details, the Examples Menu is displayed as shown on this slide. To run an example, specify its number (displayed in green text) and press Enter. The selected example is executed and, upon completion, the Examples Menu is presented again, offering the chance to run more examples.
✱ NOTE: Examples in this project are very basic and intended to show how to call individual methods in the Geotab Data-Only Plan API. In order to make each example as basic as possible, some examples build upon others and must be executed in sequence. For instance, the AddDeviceAsync example must be run before it is possible to run the SetDeviceAsync or RemoveDeviceAsync examples. If an attempt is made to run an example that relies on another example being run first, an error message is displayed notifying of this requirement.
! IMPORTANT: When running these examples, clean-up should be done to ensure that any added data is removed. For example, if the AddUserAsync example is run, it adds a user to the current database. The RemoveUserAsync example should be run to remove the added user before exiting the application or running the AuthenticateAsync example. Otherwise, it is necessary to manually clean-up any data that was added.
Geotab.DataOnlyPlan.API.Examples.FleetMonitor
The Geotab.DataOnlyPlan.API.Examples.FleetMonitor project is a comprehensive example that serves as a basis for the development of MyGeotab integrations using the Geotab Data-Only Plan API. It uses data feeds to track vehicles and output data to files and is configurable, providing abilities to:
- Track specific vehicles or dynamically track vehicles as data is received;
- Capture GPS data (LogRecords) for all tracked vehicles;
- Optionally track any number of diagnostics (StatusData and/or FaultData);
- Start feeds based on feed tokens, specific date/time or current date/time;
- Specify the feed interval; and
- Specify output folder and maximum file size
An object model diagram for the Fleet Monitor example can be found on this slide. Subsequent slides in the same presentation highlight the various objects and provide details to give a high-level understanding of the application. The section of the presentation starting at this slide provides a visual walk-through of the Fleet Monitor example logic — a conceptual overview without delving into the actual code. A review of these slides may assist in gaining a much quicker understanding as compared to relying solely on the code comments and analysis of the code.
Configuration File
The Fleet Monitor example requires a pipe-delimited CSV configuration file. A sample — Config_FleetMonitor.csv — is included in the project files. The table below provides descriptions for the parameters in the configuration file.
Parameter | Description |
VehicleTrackingOption | Must be set to one of the following values:
|
SpecificVehiclesToTrack | A comma-separated list of device IDs that correspond to vehicles to be tracked (e.g. b1,b2). Only used if the VehicleTrackingOption parameter is set to Specific. |
DiagnosticsToTrack | A comma-separated list of diagnostic IDs that correspond with diagnostics (StatusData or FaultData) that are to be monitored for tracked vehicles (e.g.DiagnosticOdometerAdjustmentId,DiagnosticFuelLevelId,DiagnosticFuelUnitsId,DiagnosticCrankingVoltageId,DiagnosticInvalidGpsMessagesReceivedId). |
FeedStartOption | Must be set to one of the following values:
|
FeedStartSpecificTimeUTC | Only used if the FeedStartOption parameter is set to SpecificTime. The UTC time (formatted as yyyy-MM-ddTHH:mm:ssZ) at which to start all data feeds (e.g. 2020-01-13T08:00:00Z). |
FeedIntervalSeconds | The number of seconds to wait, after processing a batch of feed results, before executing the next iteration of data feed calls (e.g. 30). |
OutputFolder | The folder where output data, including feed result token files and output data files, is written (e.g. C:\Temp). |
MaximumFileSizeMB | The maximum size, in megabytes, that a file may reach before a new file is started (e.g. 1). For example, if a file named GPS Data - DeviceID b1 FileID 20200113113618.csv has has reached this maximum, a new file named GPS Data - DeviceID b1 FileID 20200114081532.csv may be created and GPS data for the subject vehicle is written to the new file until the size limit is reached again. |
Running the Fleet Monitor Example
Once the configuration file is created and the parameter values are set up, the Geotab.DataOnlyPlan.API.Examples.FleetMonitor example can be run.
On start-up, a console window is displayed and the user is prompted to enter a MyGeotab server and database to run against, along with MyGeotab credentials. Upon successful authentication using these supplied details, the user is prompted to enter the folder containing the configuration file (e.g. C:\Temp) and the name of the configuration file (e.g. Config_FleetMonitor.csv). From there, processing begins — and proceeds indefinitely — following the logic outlined in the Fleet Monitor Example - Logic section of the presentation.
During processing, the console window provides constant feedback relating to execution of the data feeds and summary information is presented as shown in the screenshot on this slide.
Data received via the feeds for tracked vehicles is written to the output folder. Each file contains information for a single tracked vehicle identified by the device ID in the filename. GPS (LogRecord), StatusData and FaultData records are written to separate files, which are created only if those types of data are received for a given tracked vehicle.
Examples of the three types of output file are shown in the following slides:
