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:
- 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:
- class mygeotab.api.MyGeotabException(full_error, *args, **kwargs)[source]#
There was an exception while handling your call.
- 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.
- 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:
- __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:
- 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:
- 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:
- 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
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.