API#

The full API reference for all public classes and functions.

Querying Data#

class mygeotab.api.API(username, password=None, database=None, session_id=None, server='my.geotab.com', timeout=300, proxies=None, cert=None)[source]#

A simple and Pythonic wrapper for the MyGeotab API.

__init__(username, password=None, database=None, session_id=None, server='my.geotab.com', timeout=300, proxies=None, cert=None)[source]#

Initialize the MyGeotab API object with credentials.

Parameters:

username (str) – The username used for MyGeotab servers. Usually an email address.
password (str) – The password associated with the username. Optional if session_id is provided.
database (str) – The database or company name. Optional as this usually gets resolved upon authentication.
session_id (str) – A session ID, assigned by the server.
server (str or None) – The server ie. my23.geotab.com. Optional as this usually gets resolved upon authentication.
timeout (float or None) – The timeout to make the call, in seconds. By default, this is 300 seconds (or 5 minutes).
proxies (dict or None) – The proxies dictionary to apply to the request.
cert (str or Tuple or None) – The path to client certificate. A single path to .pem file or a Tuple (.cer file, .key file).

Raises:

Exception – Raises an Exception if a username, or one of the session_id or password is not provided.

call(method, **parameters)[source]#

Makes a call to the API.

Parameters:

method (str) – The method name.
parameters – Additional parameters to send (for example, search=dict(id=’b123’) ).

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The results from the server.

Return type:

dict or list

multi_call(calls)[source]#

Performs a multi-call to the API.

Parameters:

calls (list((str, dict))) – A list of call 2-tuples with method name and params (for example, (‘Get’, dict(typeName=’Trip’)) ).

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The results from the server.

Return type:

list

get(type_name, **parameters)[source]#

Gets entities using the API. Shortcut for using call() with the ‘Get’ method.

Parameters:

type_name (str) – The type of entity.
parameters – Additional parameters to send. A parameter called resultsLimit or results_limit will limit the number of entries returned. A search parameter can further limit results, for example search=dict(id=’b123’). If a parameter called search is omitted, any additional parameters are automatically added to a search dictionary. This simplifies basic usage. The following are equivalent calls: api.get(“Device”, search={“id”:”b2”}) api.get(“Device”, id=”b2)

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The results from the server.

Return type:

list

add(type_name, entity)[source]#

Adds an entity using the API. Shortcut for using call() with the ‘Add’ method.

Parameters:

type_name (str) – The type of entity.
entity (dict) – The entity to add.

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The id of the object added.

Return type:

str

set(type_name, entity)[source]#

Sets an entity using the API. Shortcut for using call() with the ‘Set’ method.

Parameters:

type_name (str) – The type of entity.
entity (dict) – The entity to set.

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

remove(type_name, entity)[source]#

Removes an entity using the API. Shortcut for using call() with the ‘Remove’ method.

Parameters:

type_name (str) – The type of entity.
entity (dict) – The entity to remove.

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

authenticate()[source]#

Authenticates against the API server.

Raises:

AuthenticationException – Raises if there was an issue with authenticating or logging in.
MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

A Credentials object with a session ID created by the server.

Return type:

Credentials

static from_credentials(credentials)[source]#

Returns a new API object from an existing Credentials object.

Parameters:: credentials (Credentials) – The existing saved credentials.
Returns:: A new API object populated with MyGeotab credentials.
Return type:: API

class mygeotab.api.MyGeotabException(full_error, *args, **kwargs)[source]#

There was an exception while handling your call.

__init__(full_error, *args, **kwargs)[source]#

Initialize MyGeotabException with the full error from the server.

Parameters:: full_error – The full JSON-decoded error.

class mygeotab.api.TimeoutException(server, *args, **kwargs)[source]#

The request timed out while handling your request.

__init__(server, *args, **kwargs)[source]#

Initialize TimeoutException with the server name.

Parameters:: server – The server ie. my23.geotab.com.

property message#: The excepton message.

Credentials & Authentication#

class mygeotab.api.Credentials(username, session_id, database, server, password=None)[source]#

The MyGeotab Credentials object.

__init__(username, session_id, database, server, password=None)[source]#

Initialize the Credentials object.

Parameters:

username (str) – The username used for MyGeotab servers. Usually an email address.
session_id (str) – A session ID, assigned by the server.
database (str or None) – The database or company name. Optional as this usually gets resolved upon authentication.
server (str or None) – The server ie. my23.geotab.com. Optional as this usually gets resolved upon authentication.
password (str or None) – The password associated with the username. Optional if session_id is provided.

get_param()[source]#

A simple representation of the credentials object for passing into the API.authenticate() server call.

Returns:: The simple credentials object for use by API.authenticate().
Return type:: dict

class mygeotab.api.AuthenticationException(username, database, server, *args, **kwargs)[source]#

Unsuccessful authentication with the server.

__init__(username, database, server, *args, **kwargs)[source]#

Initialize AuthenticationException with username, database, and server.

Parameters:

username – The username used for MyGeotab servers. Usually an email address.
database – The database or company name.
server – The server ie. my23.geotab.com.

property message#: The exception message.

Date Helpers#

mygeotab.dates#

Date helper objects for timezone shifting and date formatting for the MyGeotab API.

mygeotab.dates.format_iso_datetime(datetime_obj)[source]#

Formats the given datetime as a UTC-zoned ISO 8601 date string.

Parameters:: datetime_obj (datetime) – The datetime or date object.
Returns:: The datetime object in 8601 string form.
Return type:: datetime

mygeotab.dates.localize_datetime(datetime_obj, tz=<UTC>)[source]#

Converts a naive or UTC-localized date into the provided timezone.

Parameters:

datetime_obj (datetime) – The datetime object.
tz (datetime.tzinfo) – The timezone. If blank or None, UTC is used.

Returns:

The localized datetime object.

Return type:

datetime

Extras#

EntityList#

class mygeotab.ext.entitylist.API(username, password=None, database=None, session_id=None, server='my.geotab.com', timeout=300, proxies=None, cert=None)[source]#

An experimental wrapper around the base MyGeotab API class that adds some helper methods to results when retrieving results with get().

get(type_name, **parameters)[source]#

Gets entities using the API. Shortcut for using call() with the ‘Get’ method. This returns an EntityList with added convience methods.

Parameters:

type_name (str) – The type of entity.
parameters – Additional parameters to send.

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The results from the server.

Return type:

EntityList

__init__(username, password=None, database=None, session_id=None, server='my.geotab.com', timeout=300, proxies=None, cert=None)[source]#

Initialize the MyGeotab API object with credentials.

Parameters:

username (str) – The username used for MyGeotab servers. Usually an email address.
password (str) – The password associated with the username. Optional if session_id is provided.
database (str) – The database or company name. Optional as this usually gets resolved upon authentication.
session_id (str) – A session ID, assigned by the server.
server (str or None) – The server ie. my23.geotab.com. Optional as this usually gets resolved upon authentication.
timeout (float or None) – The timeout to make the call, in seconds. By default, this is 300 seconds (or 5 minutes).
proxies (dict or None) – The proxies dictionary to apply to the request.
cert (str or Tuple or None) – The path to client certificate. A single path to .pem file or a Tuple (.cer file, .key file).

Raises:

Exception – Raises an Exception if a username, or one of the session_id or password is not provided.

add(type_name, entity)[source]#

Adds an entity using the API. Shortcut for using call() with the ‘Add’ method.

Parameters:

type_name (str) – The type of entity.
entity (dict) – The entity to add.

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The id of the object added.

Return type:

str

authenticate()[source]#

Authenticates against the API server.

Raises:

AuthenticationException – Raises if there was an issue with authenticating or logging in.
MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

A Credentials object with a session ID created by the server.

Return type:

Credentials

call(method, **parameters)[source]#

Makes a call to the API.

Parameters:

method (str) – The method name.
parameters – Additional parameters to send (for example, search=dict(id=’b123’) ).

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The results from the server.

Return type:

dict or list

static from_credentials(credentials)[source]#

Returns a new API object from an existing Credentials object.

Parameters:: credentials (Credentials) – The existing saved credentials.
Returns:: A new API object populated with MyGeotab credentials.
Return type:: API

multi_call(calls)[source]#

Performs a multi-call to the API.

Parameters:

calls (list((str, dict))) – A list of call 2-tuples with method name and params (for example, (‘Get’, dict(typeName=’Trip’)) ).

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

Returns:

The results from the server.

Return type:

list

remove(type_name, entity)[source]#

Removes an entity using the API. Shortcut for using call() with the ‘Remove’ method.

Parameters:

type_name (str) – The type of entity.
entity (dict) – The entity to remove.

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

set(type_name, entity)[source]#

Sets an entity using the API. Shortcut for using call() with the ‘Set’ method.

Parameters:

type_name (str) – The type of entity.
entity (dict) – The entity to set.

Raises:

MyGeotabException – Raises when an exception occurs on the MyGeotab server.
TimeoutException – Raises when the request does not respond after some time.

class mygeotab.ext.entitylist.EntityList(data, type_name)[source]#

The customized result list

__init__(data, type_name)[source]#

Gets entities using the API. Shortcut for using call() with the ‘Get’ method.

Parameters:

data (list) – The list of result data.
type_name (str) – The type of entity.

sort_by(key, reverse=False)[source]#

Returns an EntityList, sorted by a provided key.

Parameters:

key (str) – The key to sort the data with.
reverse (bool) – If true, reverse the sort direction.

Return type:

EntityList

property first#

Gets the first entity in the list, if it exists.

Return type:: dict

property last#

Gets the last entity in the list, if it exists.

Return type:: dict

property entity#

Like first, but first asserts that there is only one entity in the results list.

Return type:: dict

to_dataframe(normalize=False)[source]#

Transforms the data into a pandas DataFrame

Parameters:: normalize (bool) – Whether or not to normalize any nested objects in the results into distinct columns.
Return type:: pandas.DataFrame

Data Feed#

class mygeotab.ext.feed.DataFeed(client_api, listener, type_name, interval, search=None, results_limit=None)[source]#

A simple wrapper for the MyGeotab Data Feed. Create a listener that inherits from DataFeedListener to pass in.

__init__(client_api, listener, type_name, interval, search=None, results_limit=None)[source]#

Initializes the DataFeed object.

Parameters:

client_api – The MyGeotab API object.
listener – The custom DataFeedListener object.
type_name – The type of entity.
interval – The data retrieval interval (in seconds).
search – The search object.
results_limit – The maximum number of records to return.

start(threaded=True)[source]#

Start the data feed.

Parameters:: threaded – If True, run in a separate thread.

class mygeotab.ext.feed.DataFeedListener[source]#

The abstract DataFeedListener to override

abstract on_data(data)[source]#

Called when rows of data are received.

Parameters:: data – A list of data objects.

abstract on_error(error)[source]#

Called when server errors are encountered. Return False to close the stream.

Return type:: bool
Parameters:: error – The error object.
Returns:: If True, keep listening. If False, stop the data feed.