Reference Guide

April 2025



Introduction

The Geotab Integrations: Software and Hardware Technical Toolkit reference guide provides a comprehensive toolkit to help you build effective integrations with Geotab using both software and hardware.

1. For software integrations – This section guides you through the integration options, the Geotab Software Development Kit (SDK), and MyGeotab, providing the resources you need to get started. You'll find information on SDK documentation, Add-Ins, commonly used tools, and important concepts.
2. For hardware integrations – This section guides you through the integration options, the Geotab Hardware Development Kit (HDK), and MyGeotab, equipping you with the essentials for successful hardware integration. We'll cover Add-On devices, custom telematics options, IOX integration, and data flow.

Software Technical Toolkit

Access development resources and important technical requirements for your solution.

SDK documentation

Introduction

It’s important to have in mind that Geotab API is a MyGeotab API, not a GO device API; you get the data from the Geotab cloud, not directly from the device; Geotab is acting as a middleware.

The MyGeotab SDK (Software Development Kit) provides a powerful set of tools for automating tasks and working with the data in MyGeotab.

Uses for the SDK:

1. Importing, exporting and synchronizing data
2. Automating tasks

Important resources

Use the SDK Reference page to see the full list of APIs (Methods and Objects) available in the SDK:

1. How to Use the SDK Reference Page
2. SDK Reference Page

Use the SDK Runner to test APIs against your MyGeotab database. Login with the same credentials as you use to login to the MyGeotab platform. You don’t need to change the server name.

1. SDK Runner

Add-In examples are linked for additional guidance. Standalone applications in JS and .NET are also linked.

1. Add-In Samples
2. JavaScript Applications
3. .NET Applications
4. .NET MyGeotab API Adapter

.Net MyGeotab API Adapter

The MyGeotab API Adapter is an application that uses the Geotab API to stream data from a MyGeotab database into a relational database in your environment.

Data can then be extracted from the adapter database for integration into:

1. Your database, data warehouse, or data lake
2. Your application
3. Third-party applications or platforms

Resources:

1. MyGeotab API Adapter Presentation
2. Solution and Implementation Guide
3. MyGeotab API Adapter and Data Optimizer
4. Data Optimizer Guide
5. Code on Github

Commonly-used API objects

An area newcomers often struggle with is the concept of how data is broken down within Geotab. We have what we call Entities, which would be things like "user", "route" and "vehicle". Additional information about common entities are detailed in our SDK.

Geotab recognizes the value of APIs; our own systems use APIs extensively to communicate with one another to automate as much work as possible. We have several APIs available which can be used by developers to interact with the raw data seen in the MyGeotab application such as devices, trips, GPS data, and engine data.

When building your integration, you will likely use the following most commonly-used API calls:

1. Device
2. ExceptionEvent (Rule triggers)
3. Diagnostic
4. 1. Status Data (Engine measurements)
   2. Fault Data
4. LogRecord (GPS data)
5. User
6. Zone
7. Group

Diagnostics

Items such as odometer, oil life remaining, battery, and so on would most likely fall into what we call Diagnostic or Status Data (Metrics collected by the vehicle). You can see the list of diagnostics collected by Geotab for a particular vehicle in your database using a script as shown here: How to query all metrics of a GO device?

Within Geotab UI, you can view all the measurements collected in the Engine & Maintenance section, as explained in section 7 in the Product Guide.

✱ NOTE: First you need to know what diagnostic you are looking for and then find the best way to get that diagnostic, not the other way around. There are thousands of diagnostics available, and if you don’t know what you are looking for, it will be like finding a needle in a haystack.

For a list of diagnostics, their descriptions, and their ids in MyGeotab, please refer to these resources:

List of Diagnostics and Sources with IDs, and MyGeotab Diagnostics.

Known IDs

The system Known IDs give you a list of all the well-known IDs available in the SDK. Here you can see the IDs for the most popular diagnostics like odometer, fuel level, seatbelts, tire pressure, and more.

Have in mind that not every diagnostic is included in this list, just the most popular ones. The diagnostics not included in this list don’t have a friendly name, but they are perfectly valid.

API clients

The MyGeotab API is language-agnostic and can be accessed from all languages that support HTTP requests. For more information, refer to HTTP Requests in Javascript.

There are a number of language-specific API clients that make it easier to develop in the language of your choice.

Available API clients:

1. .NET
2. Javascript
3. Node.js
4. Python
5. PHP

Special concepts

Various concepts will improve the performance of your solution, and let you avoid simple errors.

1. Data Feed (Data Streaming)
2. 1. Data Feed Overview
   2. GetFeed API
2. Rate Limits
3. MultiCalls
4. Caching
5. Unit of measure
6. Working with dates
7. Authentication concepts

Data Feed

The data feed is the primary method used to synchronize data quickly from the telematics system to another system using the API. The GetFeed method can be polled at intervals to get new and updated data from the system. The feed API works with a token that is passed on every request and sent back with the payload on every response. This allows Geotab to track “up to which point in time” we have already sent the receiver data. It also allows the receiver to stop and seamlessly resume the data feed.

Rate Limits

Rate limits refer to the rate at which an API call can be made. For example, the Authenticate API call can have no more than 10 requests-per-minute. Knowing what the rate limit is for an API call is really important to avoid rate limit exceptions.

MultiCall

A MultiCall is a way to make several API calls against a server with a single HTTP request. This eliminates potentially expensive round-trip costs.

Making an HTTP request over a network has overhead. This can be in the form of Network overhead, the round trip time to send and receive data over the network, and HTTP overhead, the HTTP request, and response headers. A MultiCall can be used to reduce the amount of overhead in situations where many small requests need to be made to a server.

Add-In introduction

An Add-In is JavaScript, HTML, and CSS loaded into the MyGeotab or Geotab Drive platforms. Your Add-In lives inside the user interface (UI) of these platforms so users can access both ours and your solution for a seamless experience.

✱ NOTE: MyGeotab consists of a web application and a mobile app. Geotab Drive consists of a mobile app.

Types of Add-Ins

Important resources:

1. Developing Add-Ins (Page and Button)
2. Geotab Drive Add-Ins
3. Map Add-Ins
4. Sample Add-Ins

Add-In lifecycle and configuration file

Building an Add-In requires a configuration file and a lifecycle implementation to control how the Add-In responds to user interaction.

Resources:

1. Developing Add-Ins page
2. 1. Lifecycle of an Add-In
   2. Configuration file

Installing Add-Ins to a database

These steps explain how users install your Add-In into the MyGeotab platform.

A banner is displayed to indicate that the Add-In has been successfully installed.

These steps can be followed by whoever has access to the database and the permission to add Add-Ins. By default both the Customer and Partner can follow this installation process. You can also choose to request database access for someone from your organization to perform the installation.

Add-In generator

The Add-In generator is a useful tool that allows emulating the MyGeotab environment for the creation and testing of Add-Ins.

The generator has the following features:

1. Local debugging: Run and debug the Add-In locally without having to add to the test database.
2. Release build process: Provides commands for creating a build of the Add-In.
3. Unit testing: Spec testing with Mocha and Chai. Functional testing with Puppeteer.

Best practices

This section describes a series of best practices for creating a robust software integration.

✱ NOTE: The outlined practices are a requirement for Geotab Marketplace Partners and we encourage everyone creating a solution with Geotab to follow them for a smooth development process and user experience.

Code hosting

Your Add-In files should be hosted online by your organization. Your configuration file must link to that hosting location in the URL and Icon properties.

Uploading your files into Geotab Customer databases is not recommended because those files cannot be updated remotely.

CSS class names

Your CSS class names should not use the same names as the classes in the MyGeotab platform.

The requirement is to rename your classes so they have your Add-In name (or an abbreviation of it) in front of them, followed by an icon.

For example, for an Add-In named “My Awesome Add-In”, the CSS classes should start with “MAA”, such as “MAA_header1”.

If your Add-In name is one word, use the name instead of the abbreviation.

Access control

A MyGeotab database can consist of lots of people, such as an IT professional, a fleet manager, a technician, a truck driver, and more. Most of the time, not all of these users should receive access to your solution. Your Add-In must control who is able to access it.

There are two ways this is usually done; you can choose either or discuss a new way with your SE:

1. New users who want to use your solution in MyGeotab must be registered by an administrator in your system. This way only registered users are given access to the Add-In.

2. ✱ NOTE: SSO still applies for the registered users.

2. Your Add-In must check the security clearance of the active user, and deny access if they do not have a high enough clearance. Usually “Administrator” and “Supervisor” are used as the allowed clearances. The security clearance can be found with a “Get” API call on the “User” object and including a ‘search’ parameter for the user’s username (the username can be found with a getSession call). It will be in the “securityGroups” array.

Syncing users, vehicles, and more from MyGeotab to your platform

MyGeotab users must be automatically registered in your platform by the time they navigate to your Add-In.

Manual registration of users/vehicles/etc (any objects under the database) in your Add-In must be avoided. This includes registration of users, vehicles, and more in a platform outside of MyGeotab to be able to use them within your Add-In.

The exception to this are data points required by your platform that are not available in MyGeotab - these can be requested within your Add-In.

If your platform requires data that is available in the MyGeotab platform, it can use the MyGeotab APIs to access that data. For example, vehicle Make/Model/Year, user name, groups, and so on.

Single Sign-On (SSO)

Refer to Single Sign-On Process for more information.

User group

Within the MyGeotab platform, users can be placed into Groups, which limits their visibility to only the vehicles, users, and data in that group.

For example, User1 is placed into a group called “ExampleGroup”.

1. “ExampleGroup” contains 3 other users and 5 devices.
2. When User1 navigates to the Assets page, they will see only those 5 devices. When User1 navigates to the Users & Drivers page, they will see only those 3 other users (plus themselves). When User1 views available engine data, they can only query the 5 devices in their group.
3. The actual database might have many more devices in it, but those devices are not visible to User1 because they are not in the same Group as User1.

When you use getSession to make API calls on behalf of the active user, the API call results are already limited based on the user’s group.

Your solution should make a Get User and Get Device API call when the user navigates to the solution. The results of those API calls will be a list of Devices and Users that the active user has visibility to. Only information related to those Devices and Users should be displayed within your solution. The same thing must be done for other data displayed in your solution, for example Zones, Rules, Exception Events, Status Data, Fault Data, and so on.

For more information about groups, refer to the Product Guide.

Service Accounts

Service accounts are used exclusively by your solution to make API requests against the MyGeotab database outside of user sessions.If it makes sense for your solution to use service accounts, implement them by following all requirements in the Service Account Guidelines document.

Pay close attention to:

1. The username
2. The password strength
3. The security clearance
4. The number of logins performed

Group filtering

Within MyGeotab, users can use the Group Filter at the top-left of the page to limit their view to the vehicles, users, and data within the Groups they choose. Your solution must read this Group Filter state and filter your data accordingly.

For example, if the user is in Company Group (the highest possible Group) and there are 10 vehicles in a database, when the user uses the Group Filter to select a Group that contains only two vehicles, they will only see those two vehicles on the Vehicles page. Similarly, when they open your solution, they should only see information relating to those two vehicles.

Use state.getGroupFilter() to get the Group Filter state. Refer to the Geotab SDK for more information.

This returns the id of the Group selected by the user in the Group Filter. If it is empty, then the user is in the default group (Company Group), and the id "GroupCompanyId" is returned. Only objects belonging to this Group should be displayed within your solution; this can be done by looking at the “groups” property of the device, user, zone, etc. objects.

Timezone

Users can change their timezone in the MyGeotab platform.

Your Add-In must either use the timezone of the user’s computer or adapt to the MyGeotab timezone setting of the user.

The timezone of the active user can be found with a “Get” API call on the “User” object and including a ‘search’ parameter for the user’s username (the username can be found with a getSession call). It will be in the “timeZoneId” property.

api.call("Get", {

"typeName": "User",

"search": {"name" : "johnsmith@gmail.com"}

});

Units of measurements

Users can change their units of measurements between metric and imperial.

Your Add-In must adapt to the setting chosen by the user.

The unit of measurement of the active user can be found with a “Get” API call on the “User” object and including a ‘search’ parameter for the user’s username (the username can be found with a getSession call). It will be in the “isMetric” boolean value.

api.call("Get", {

"typeName": "User",

"search": {"name" : "johnsmith@gmail.com"}

});

Add-In icon

Add-Ins that exist as custom pages of MyGeotab must follow Geotab's design specifications when creating their Add-In icons.

Use this tool to confirm your icon meets the requirements: MyGeotab Icon Validator Tool.

Accessibility

We recommend Add-Ins achieve compliance with WCAG 2.2 Level AA accessibility.

Automated tools such as Chrome Lighthouse can test the majority of these requirements. For the remaining requirements, Lighthouse provides a list of manual test steps that can be done using a screen reader such as VoiceOver.

Important notes

1. Changes to the Geotab URL scheme have been implemented to allow all API traffic to flow through a single federation gateway without redirection to a specific server. In the SDK Concepts section on Authentication, authentication requests should not be made to a particular server, rather, they should be made to the root federation server (such as my.geotab.com). You should expect the following:
2. 1. All responses will behave as described in "Example 1: Request To The Correct Server", with results returning a 'ThisServer' path.
   2. Example 2: “Request Redirected To Correct Server" should not be expected to occur.
   3. Example 3: “Requests With Missing Databases Or With Expiring Credentials" still applies in those conditions.
2. You will be using a different service account in each Geotab customer database.
3. Geotab does not allow the following functionality within any integrations or solutions using Geotab data:
4. 1. The solution can’t affect the drivability of the vehicle.
   2. 1. It cannot remotely or locally affect vehicle responsiveness or driving characteristics (for example, ignition status, speed, steering input, suspension).
   1. The solution can’t contain any stop engine or anti-jammer technology.

   Common pitfalls to avoid

   1. Improper use of Authorization / Session ID: The session ID returned when doing an auth in MyGeotab is good for up to 2 weeks! Don't waste trips to the server and back for unnecessary auths.
   2. GetFeed doesn't need a break: 60-times-a-minute per user is a lot of feeds, and it can handle it. Get the data, do what you want with it, and poll again. Don't add in any kind of wait time. If it's been a second since you called it, you're good to call again without issue.
   3. Misunderstanding of the rate limit: Get, Set, and Add calls are not rate-limited; only Auth and GetFeed are. The GetFeed limit applies per user login and per entity. While commonly assumed to be per user, remember the per-entity limit: StatusData and LogRecord each have separate 60 calls-per-minute allowance.
   4. Forgetting about MultiCall: If you need to do a bunch of Get / Set / etc, wrap it in a multi-call. You eliminate a lot of overhead. The only time you shouldn't use a multi-call is for getfeeds and critical 'add' calls, as there is no transaction rollback functionality.
   5. Misconceptions how Geotab samples data: Please review the information about the curve-logging algorithm. Geotab doesn’t use a time-based or distance-based approach. The curve-logging algorithm is a more efficient method.

   Frequently asked questions (FAQs)

   Can I have a Geotab database?

   Yes, if you don’t already have one, contact your Geotab Business Development Manager or create one.

   How do I make API calls when a user is using my Add-In?

   Use the getSession() API call to get the active user’s credentials; then use these to make API calls against MyGeotab.

   How do I make API calls outside of a user’s session?

   To make API calls outside a user’s session, use a service account. Refer to Service Account Guidelines for more information.

   Is there a Beta environment where I can test my Add-In with new versions of the MyGeotab platform?

   Yes, you can register a database in the Beta environment on MyPreview. The Preview version gets pushed to production about every 4 weeks.

   Are there any integrations the Geotab Marketplace doesn’t allow?

   Geotab prohibits products and services that remotely or locally affect vehicle responsiveness or driving characteristics including ignition status, speed, steering input, suspension, and more.

   Stay informed: SDK updates

   Keep up-to-date on SDK changes with the following resources:

   1. Geotab Blog – Subscribe to the Geotab Blog. The Updates Category contains SDK updates that could affect your integration.
   2. SDK What’s New – View the SDK What’s New page regularly for deeper documentation on SDK changes.
   3. Geotab Community – Join the Geotab Community to connect with Geotab experts.
   4. DEV Channel – Find development guidelines on Geotab’s Dev Channel.

   Hardware Technical Toolkit

   Access development resources and important technical requirements for your solution.

   Add-On vs. Custom Telematics Device

   How is the Geotab GO device used?

   Determine if your integration is best suited to be a hardware Add-On or Custom Telematics Device. Here are the main differences between the two:

   1. Hardware Add-On – A peripheral sensor or controller which connects to the GO device via an IOX in order to exchange data.
   2. Custom Telematics Device – A standalone telematics device which replaces the need for a GO device in a vehicle or asset.

   Resources:

   1. Geotab Firmware Product Guide
   2. Hardware Add-On Integration
   3. Custom Telematics Device Integration

   IOX integration options

   Types of interfaces

   IOX	Type of interface
   IOX-RS232	A standard RS232 physical interface with optional power supply wiring included outside of the connector.
   IOX-USB	A standard USB physical interface for charging/powering and data communication with a hardware add-on.
   IOX-CAN	A CAN physical interface through a keyed mini-USB type-B plug.
   IOX-BT	A Bluetooth receiver which monitors select sensor-enabled beacons.
   Custom IOX	A partner-designed and programmed custom IOX.

   Resources:

   1. IOX-RS232 Specifications
   2. IOX-USB Specifications
   3. IOX-CAN Specifications
   4. IOX-BT Specifications
   5. Custom IOX Specifications

   Communication protocols

   IOX	Communication protocol
   IOX-RS232	Leverages the Geotab hardware Add-On protocol exclusively.
   IOX-USB	Leverages the Geotab hardware Add-On protocol exclusively.
   IOX-CAN	Leverages the Geotab hardware Add-On protocol with less message type support, and can also leverage CAN messages as well.
   IOX-BT	Leverages the Geotab hardware Add-On protocol for BLE applications which contains a specifically structured advertising packet.
   Custom IOX	Primarily leverages the IO Expander protocol and secondarily, can behave like any other IOX for data exchange.

   Resources:

   1. RS232 & USB Protocol
   2. CAN Protocol
   3. BLE Protocol
   4. IO Expander Protocol

   Data types

   IOX	Data types
   IOX-RS232	Status Data, Custom Data, Binary Data, GO Device Data, Cloud Data
   IOX-USB	Status Data, Custom Data, Binary Data, GO Device Data, Cloud Data
   IOX-CAN	Status Data, CAN Data, Cloud Data
   IOX-BT	Status Data, Custom Data
   Custom IOX	Status Data, Custom Data, Binary Data, GO Device Data, CAN Data, Cloud Data

   Feature comparison matrix

   	Add-On Protocol	Status Data	Custom Data	Binary Data	Two-Way Cloud Communication	Two-Way Local Communication
   IOX-RS232	✔	✔	✔	✔	✔	✔
   IOX-USB	✔	✔	✔	✔	✔	✔
   IOX-CAN	✔	✔	✘	✘	✔	✘
   IOX-BT	✔	✔	✔	✘	✘	✘
   Custom IOX	✔	✔	✔	✔	✔	✔

   Custom Telematics Device options

   Types of Custom Telematics Devices

   1. Standard Custom Telematics Device – A non-Geotab device which replaces the GO device in a vehicle or asset. Typically functions as an asset tracker without the capability of sending richer engine data like VIN, odometer, engine hours, fuel usage, and more. Can be integrated into Geotab’s platform using the DIG system.
   2. Custom Vehicle Device – A non-Geotab telematics device capable of reporting vehicle specific details like VIN, odometer, engine hours, fuel usage, seat belt, and more. Can be integrated into Geotab’s platform using the DIG system.

   Resources:

   1. Custom Telematics Device Integration Overview
   2. Request a ProductId for Provisioning

   Custom Telematics Device API overview

   

   APIs for Device Management - MyAdmin

   1. Authenticating – Authenticate() requires a MyAdmin account with the specific MyAdmin API role (role: MyAdminApiUser) enabled.
   2. Provisioning – Once authenticated, the resulting apiKey and sessionId are used in the ProvisionDevice() call which creates a serial number for the provided ProductId that can then be added to a MyGeotab database.

   Refer to the MyAdmin SDK for more information.

   APIs for Data Sending - Data Intake Gateway

   Authenticating

   1. Requires a MyAdmin account with the specific DIG API role (role: DIG-Access) enabled
   2. A request to /authentication/authenticate gives the user a refresh token and bearer token with their corresponding creation and expiry times.

   Sending Data

   1. Once authenticated, the resulting bearer token is used as a header in a POST request to /records
   2. A 202 ACCEPTED response will be returned once DIG receives the records whether valid or not

   Invalid Records

   1. The integrator must periodically make a GET call to /invalidrecords to retrieve records that were flagged as invalid

   Resources:

   1. Data Intake Gateway (DIG) Guide
   2. DIG Authentication Workflow
   3. DIG Records Workflow
   4. Migrating to DIG for Existing Integrations

   Data Intake Gateway Architecture

   

   Device availability and retrieval

   Storage of Data in MyGeotab Databases

   Data sent from an Add-On or Custom Telematics Device travels through Geotab gateway servers into a MyGeotab database, where it is available for consumption. There are typically minor inherent delays involved in this process. Data becomes available in MyGeotab directly through the UI or through API, or both.

   Data available through the MyGeotab UI and API

   Status Data from Add-Ons and Custom Telematics Devices can be accessed through the MyGeotab UI and API.

   To leverage Rules and Reports within MyGeotab, the data is best entered as Status Data (MyGeotab Engine Measurements).

   Data available through the MyGeotab API, only

   For Add-Ons, Custom Data and Binary Data types are only accessible through the MyGeotab API.

   ✱ NOTE: Binary Data is Passthrough only and so is not stored for later uploading when the GO device is out of data coverage. Retrying is necessary for this use case.

   Resources:

   1. Geotab System Architecture
   2. MyGeotab Landing Page
   3. StatusData API
   4. CustomData API
   5. BinaryData API

   User experience

   Requirements Overview

   Creating a strong user experience involves three segments:

   Clearly Defined Diagnostics

   Make sure that your Add-On or custom telematics device is sending clearly labeled data so customers are able to take action using it.

   User Guide

   Lay out the setup process, performance expectations, and helpful tips in using your hardware product with the Geotab platform.

   Build Value Around Hardware

   Add unique software components to your resulting data to make it easier to interpret and associate to fleet performance.

   Refer to User Experience Guidelines for more information.

   Stay informed: HDK updates

   Keep up to date on HDK changes and updates with the following resources:

   1. Geotab Blog – Subscribe to the Geotab Blog. The Updates Category contains SDK updates that could affect your integration.
   2. SDK What’s New – View the HDK What’s New page regularly for deeper documentation on SDK changes.
   3. Geotab Community - Integrators Hub – Get the latest HDK updates in your inbox.
   4. DEV Channel – Find development guidelines on Geotab’s Dev Channel.