MyGeotab Node.js API Client

1.3.1 · deprecated · verified Tue Apr 21

This package, `mg-api-node`, functions as an unofficial Node.js client for programmatically interacting with the MyGeotab API. It offers capabilities for authentication, executing API calls (such as `Get`, `call`, and `multicall`), and managing request timeouts and session IDs to optimize repeated interactions. The latest stable version is 1.3.1. Its release cadence has been infrequent, with the most recent feature addition (request timeout functionality) in v1.3.0. While it once served as a direct Node.js interface for MyGeotab, this project is now officially deprecated. Users are strongly advised to transition to the `mg-api-js` package for ongoing support, new feature development, and improved maintainability.

Common errors

```
TypeError: API is not a constructor
```
cause Attempting to use `mg-api-node` with ES module `import` syntax.

fix Change your import statement to `const API = require('mg-api-node');` to correctly load the CommonJS module.
```
Error: InvalidUserException
```
cause Authentication failed due to incorrect username, password, or database name, or insufficient user permissions.

fix Double-check your `userName`, `password`, and `database` parameters. Ensure the provided user has necessary API access within the MyGeotab system.
```
Error: read ECONNRESET
```
cause The connection to the MyGeotab API server was reset, possibly due to server-side issues, network instability, or an intermediate proxy.

fix Implement robust error handling and retry mechanisms. Verify network connectivity and check MyGeotab's status page for outages. Ensure your environment's proxy settings are correct if applicable.

Warnings

breaking This project has been officially deprecated. No further development, bug fixes, or security updates will be provided for `mg-api-node`.
Fix: Migrate to the `mg-api-js` package, which is the officially supported successor. `mg-api-js` offers modern features, active maintenance, and improved API patterns.
gotcha The API exclusively uses Node.js callback patterns for asynchronous operations, which can lead to 'callback hell' in complex scenarios.
Fix: For new projects or migrations, consider `mg-api-js` which utilizes Promises/async-await. If stuck with `mg-api-node`, use utility libraries like `util.promisify` (Node.js built-in) or `async` to manage callbacks.
gotcha Authentication failures, such as `InvalidUserException`, are common if credentials or the database name are incorrect or user permissions are insufficient.
Fix: Ensure `userName`, `password`, and `database` are correct. Verify user permissions within MyGeotab. The library includes reauthentication logic for `InvalidUserException` but correct initial setup is critical.
gotcha By default, HTTP requests have no explicit timeout, potentially causing long hangs on slow network connections or unresponsive API endpoints.
Fix: From v1.3.0 onwards, you can pass a timeout (milliseconds) and an optional timeout callback to `api.call()` and `api.multicall()` to prevent indefinite waits. For example: `api.call(..., 10000, () => console.log('Request timed out'))`.

Install

npm install mg-api-node npm
yarn add mg-api-node yarn
pnpm add mg-api-node pnpm

Imports

API
wrong:
```
import API from 'mg-api-node';
```
correct:
```
const API = require('mg-api-node');
```
This library uses CommonJS `require` syntax. Attempting to use ES module `import` will result in a runtime error.
API constructor
wrong:
```
const api = mg_api_node(userName, password, database);
```
correct:
```
const api = new API(userName, password, database);
```
The primary export is a class/constructor function named `API`, which must be instantiated with `new`.

Quickstart

Demonstrates basic authentication and a 'Get' API call to fetch user data using callback patterns.

const API = require('mg-api-node');

const userName = process.env.GEOTAB_USERNAME ?? 'YOUR_USERNAME';
const password = process.env.GEOTAB_PASSWORD ?? 'YOUR_PASSWORD';
const database = process.env.GEOTAB_DATABASE ?? 'YOUR_DATABASE'; // e.g., 'geotab-live'

const api = new API(userName, password, database);

api.authenticate(function(err, data) {
  if (err) {
    console.error('Authentication Error:', err);
    return;
  }

  console.log('Authenticated successfully. User:', data.userName);

  api.call('Get', {
    typeName: 'User',
    search: {
      name: data.userName
    }
  }, function(err, userData) {
    if (err) {
      console.error('API Call Error:', err);
      return;
    }
    console.log('User Data:', userData);
  });
});

view raw JSON →