Migrating to the Altitude SDK

Overview

Altitude offers a new Python SDK, altitude-sdk, as a standalone package. The new SDK has benefits such as

• Simplified authentication: no more session management or credential storage.
• Typed domain methods: IDE autocomplete and clearer code instead of generic string-based calls.
• Automatic job handling: .all() handles polling, retries, and result extraction in one call.
• A cleaner interface.

SDK changes at a glance

Migrating to the new SDK package will affect how you install, authenticate, and make API calls. The new altitude-sdk package offers a simpler, more direct interface and is the recommended approach for any new development.

What’s New

The points below summarize the key differences between the queryType endpoints and the SDK for a migrating user:

• Input and output field names now use camelCase formatting.
• Nested inputs have been flattened. For example, dateRange is no longer passed as an object; pass dateFrom and dateTo as separate parameters instead.
• Some input and output parameter names have changed. Refer to each endpoint’s documentation for details.
• The getSavedResults endpoint has been deprecated. Each endpoint can get its own results by calling the GET results version of the endpoint with a job id.

Specific technical changes

The points below are a summary of the specific technical changes involved, migrating from the queryType endpoints to the SDK:

• Package: mygeotab → altitude-sdk
• Import: from mygeotab.altitude import AltitudeAPI → from altitude_sdk import AltitudeClient
• Authentication: username, password, database, and server → API key only
• API calls: generic client.do() with serviceName and queryType → typed domain methods (for example, client.stop_analytics.rda(params))
• Endpoint selection: queryType parameter → dedicated REST endpoints
• Results: single response object → job handler with .all() for blocking or .run() for manual control
• Base URL: altitudeserver.geotab.com → altitudeapis.geotab.com

Code comparison

Legacy code example:

In the old approach, you needed to install the mygeotab package and sign in using your Altitude username, password, and database name. Every API request was made through the client.do() method, where you had to specify which module and which type of query you wanted using text strings (serviceName and queryType). This meant you needed to know the exact internal names for each module and query type before you could make a request.

pip install mygeotab

from mygeotab.altitude import AltitudeAPI

client = AltitudeAPI(
    username="you@yourcompany.com",
    password="your_password",
    database="your_database_name",
    server="my.geotab.com"
)
client.authenticate()

api_params = {
    "serviceName": "dna-altitude-general",
    "functionParameters": {
        "queryType": "getRoadSegments",
        "asOfDate": "2025-01-01",
        "zones": [{"ZoneId": "32003", "ISO_3166_2": "US-NV", "ZoneType": "County"}]
    }
}
results = client.do(api_params)

SDK code example:

In the new approach, you install the dedicated altitude-sdk package and sign in using only an API key, a single token you generate from your user profile in the Altitude portal. Instead of routing every request through one method, the SDK gives you purpose-built methods for each module. You call the method with your parameters, add .all() at the end, and the SDK handles submitting your request, waiting for it to complete, and returning your results.

pip install altitude-sdk

from altitude_sdk import AltitudeClient

client = AltitudeClient(api_key="YOUR_API_KEY")

params = {
    "asOfDate": "2025-01-01",
    "zones": [{"code": "32003", "iso_3166_2": "US-NV", "type": "County"}]
}
results = client.stop_analytics.rda(params).all()

Getting started

The altitude-sdk package is installed using pip, Python's built-in package manager. If you have Python installed on your machine, you already have pip.

Installation

To install the altitude-sdk package, open the terminal on your computer and run the following command:

pip install altitude-sdk

This command will make the altitude-sdk package available in your Python environment. The full package documentation is available on PyPI.

Authentication

In order to use the altitude-sdk package, you will need to authenticate with an Altitude API key. Generate your API key from your user profile in the Altitude portal. See Getting Altitude Credentials for instructions.

Once you have your API key, go back to your terminal and run this command, replacing “your-api-key” with the API key you generated:

from altitude_sdk import AltitudeClient

client = AltitudeClient(api_key="your-api-key")

Making your first SDK API request

There are two ways to request data from the Altitude API, depending on what you need.

• Looking up reference data (Direct API): Some requests return information immediately. For example, you can retrieve a list of available industries or vehicle classes in a single call with no waiting. A direct API query is a synchronous reference and CRUD call.
• Running an analysis (Job process): Most Altitude requests will involve running an analytical job. When you submit a job process, the API queues it and returns a job ID immediately. The SDK waits for the job to finish and returns your results automatically when you use .all(). If you need to run several jobs at the same time and need more control, you can manage the job manually.

SDK API Request Example

The example below shows a complete Regional Domicile Analytics job process request. Replace "your-api-key" with the API key you generated earlier, update the zone and date range to match your data, and run the script in your Python environment.

from altitude_sdk import AltitudeClient

client = AltitudeClient(api_key="your-api-key")

params = {
    "zones": [{"code": "32007", "iso_3166_2": "US-NV", "type": "County"}],
    "dateRanges": [{"dateFrom": "2025-03-01", "dateTo": "2025-03-31"}],
    "generateTimeSeries": False,
}

# Submit → poll to completion → paginate → return all rows
rows = client.stop_analytics.rda(params).all()

When the job completes, your results are stored in the rows variable.

Available modules

The SDK is organized into modules, each module corresponds to a specific area of the Altitude API. Think of them as sections of a toolbox: you use client.stop_analytics to run stop-based analyses, client.zones to work with geographic zones, and so on.

The table below lists all available modules and what each one covers. When you make a request, you choose the module that matches the type of data you want.