MyGeotab Python Client

Warnings

• breaking Version 0.9.0 dropped support for Python 2.x and Python 3.6. Ensure your environment uses Python 3.7 or newer to avoid compatibility issues.
  Fix: Upgrade your Python environment to 3.7+ and then upgrade the `mygeotab` library to 0.9.0 or later: `pip install --upgrade mygeotab`.
• deprecated The `API.search()` and `API.search_async()` methods were deprecated in v0.5.0 and subsequently removed in v0.6.0. Their functionality was integrated into the `client.get()` method by using the `search` parameter.
  Fix: Replace calls like `client.search('Device', name='%Test Dev%')` with `client.get('Device', search={'name': '%Test Dev%'})`.
• gotcha When constructing JSON parameters for API calls, ensure all property names and string values are enclosed in double quotes. Using single quotes (e.g., `{'name': 'value'}` instead of `{"name": "value"}`) will result in a `Geotab.Serialization.JsonSerializerException` error from the MyGeotab API as of release 5.7.2103.
  Fix: Always use double quotes for JSON keys and string values within your API call parameters, for example: `client.get('Device', search={'name': 'MyDevice'})`.
• gotcha If you already have a `session_id`, `client.authenticate()` should generally only be called if the existing `session_id` is invalid or expired (e.g., after an `InvalidUserException`). Repeatedly calling `authenticate()` with a valid `session_id` is often unnecessary and can lead to unexpected behavior or deprecated method warnings (specifically, the undocumented usage of `Authenticate` with an authenticated credentials object was deprecated around MyGeotab 9.0 on the API side). The `ExtendSession()` method (on the API) is for extending sessions.
  Fix: Implement logic to check for session validity before authenticating. If `session_id` is present and valid, proceed directly to API calls. Only call `authenticate()` when starting a new session or re-authenticating after an `InvalidUserException`. The `mygeotab` library's `client.authenticate()` should handle the standard username/password flow correctly, but be mindful when integrating with existing session IDs.

Install

• pip install mygeotab Install stable version

Imports

• API

  from mygeotab import API

Quickstart

This quickstart demonstrates how to initialize the `mygeotab` client, authenticate using environment variables, and perform basic API calls such as retrieving devices and checking API version information. It handles potential authentication failures gracefully.

import os
from mygeotab import API

# Retrieve credentials from environment variables for security
USERNAME = os.environ.get('MYGEOTAB_USERNAME', 'your_username@example.com')
PASSWORD = os.environ.get('MYGEOTAB_PASSWORD', 'your_password')
DATABASE = os.environ.get('MYGEOTAB_DATABASE', 'YourDatabaseName')

if USERNAME == 'your_username@example.com' or PASSWORD == 'your_password':
    print("Please set MYGEOTAB_USERNAME, MYGEOTAB_PASSWORD, and MYGEOTAB_DATABASE environment variables.")
else:
    try:
        # Initialize the API client
        client = API(username=USERNAME, password=PASSWORD, database=DATABASE)
        
        # Authenticate the client
        client.authenticate()
        print(f"Successfully authenticated to database: {DATABASE}")
        
        # Example: Get the first 5 devices
        devices = client.get('Device', resultsLimit=5)
        print(f"Retrieved {len(devices)} devices:")
        for device in devices:
            print(f"  - Device ID: {device.get('id')}, Name: {device.get('name')}")
            
        # Example: Get version information (unauthenticated call example, though client is authenticated)
        version_info = client.call('GetVersion')
        print(f"API Version: {version_info.get('apiVersion')}")

    except Exception as e:
        print(f"An error occurred: {e}")