Altitude

Altitude is Geotab’s DaaS (Data as a Service) platform. AltitudeAPI is a subclass of API that routes all traffic through the Altitude proxy endpoint.

Authentication works the same way as the core API — provide credentials and call authenticate() before making any data calls.

Workflow

The typical Altitude workflow is:

  1. Submit a query job with create_job().

  2. Poll until it finishes with wait_for_job_to_complete().

  3. Retrieve paginated results with get_data().

The convenience method do() runs all three steps in sequence:

from mygeotab.altitude.wrapper import AltitudeAPI

api = AltitudeAPI(
    username='hello@example.com',
    password='mypass',
    database='MyDatabase',
)
api.authenticate()

params = {
    'serviceName': 'MyService',
    'functionParameters': {
        'startDate': '2025-01-01T00:00:00Z',
        'endDate':   '2025-01-31T00:00:00Z',
    },
}

# All-in-one: submit → wait → fetch
rows = api.do(params)

# Or step-by-step for more control:
job = api.create_job(params)
params['functionParameters']['jobId'] = job['id']
api.wait_for_job_to_complete(params)
rows = api.get_data(params)

AltitudeAPI

class mygeotab.altitude.wrapper.AltitudeAPI(username, password=None, database=None, session_id=None, server='https://altitudeapis.geotab.com/api/v1', timeout=300, proxies=None, cert=None)[source]
__init__(username, password=None, database=None, session_id=None, server='https://altitudeapis.geotab.com/api/v1', timeout=300, proxies=None, cert=None)[source]

A wrapper around mygeotab API for altitude users.

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) – Ignored for routing. All Altitude traffic is hardcoded to the proxy at https://altitudeapis.geotab.com/api/v1, which forwards requests to MyGeotab.

  • 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_api(function_name: str, params: dict) → dict[source]

Supports getJobStatus calls, and getQueryResults calls. Retries in case of errors like connection rest.

create_job(params: dict) → dict[source]

creates the job with the given params.

check_job_status(params: dict) → DaasGetJobStatusResult[source]

checks the status of a given job. jobId needs to be included in params.

wait_for_job_to_complete(params: dict) → dict[source]

waits for a job to finish running and returns the job. jobId needs to be included in params.

fetch_data(params: dict) → dict[source]

fetch data for the given params. jobId needs to be included in params.

get_data(params: dict) → list[source]

uses and iterates through fetch_data for the given params, and returns the combined data. jobId needs to be included in params.

do(params: dict) → list[source]

given the parameters, will call the request, wait on it to finish and return the combined data.

add(type_name, entity)

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:
Returns:

The id of the object added.

Return type:

str

authenticate()

Authenticates against the API server.

Raises:
Returns:

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

Return type:

Credentials

call(method, **parameters)

Makes a call to the API.

Parameters:

  • method (str) – The method name.

  • parameters – Additional parameters to send (for example, search=dict(id=’b123’) ).

Raises:
Returns:

The results from the server.

Return type:

dict or list

static from_credentials(credentials)

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

get(type_name, **parameters)

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:
Returns:

The results from the server.

Return type:

list

multi_call(calls)

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:
Returns:

The results from the server.

Return type:

list

remove(type_name, entity)

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:
set(type_name, entity)

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:

Result Types

class mygeotab.altitude.daas_definition.DaasResult(call_result: dict)[source]

DaasResult class, the base class for all results returned from calling our application from the gateway

Attributes:

call_result (dict): The result returned from the api call, this includes our gateway information. api_result (dict): The “apiResult” the result computed by altitude application. jobs (list): all the possible results returned by the altitude application call, normally it should always have the length of 1. job (dict): first result returned by the altitude application call (first element of jobs). daas_errors (list): possible errors list that happened on the gateway. api_result_errors (list): possible errors list that happened on the altitude application. api_result_error_message (str): possible single error message that happened on the altitude application. api_result_error (DaasError): possible single error object that happened on the altitude application. errors (list): list of all the errors (gateway and altitude application) combined together.

__init__(call_result: dict)[source]
class mygeotab.altitude.daas_definition.DaasGetJobStatusResult(call_result: dict)[source]

DaasGetJobStatusResult class, the returned format for checking the status of the job

Attributes:

id (str): the id of the job returned status (dict): the status of the job state (str): the state of the job (from the status object)

__init__(call_result: dict)[source]
has_finished()[source]
class mygeotab.altitude.daas_definition.DaasGetQueryResult(call_result: dict)[source]

DaasGetQueryResult class, the returned format for checking the result of the job

Attributes:

totalRows (str): the id of the job returned rows (list): the rows including the data pageToken (str): the token of the page

__init__(call_result: dict)[source]
class mygeotab.altitude.daas_definition.DaasError(error: dict)[source]
__init__(error: dict)[source]