I have never worked with an API before. How do I get started?

This guide walks you through setting up a Python notebook environment and running your first API call with the client.do() function.

The Altitude API provides programmatic access to geospatial datasets. With the Geotab Altitude Python package and a Python notebook environment, you can retrieve the data you need and use it in your own tools and workflows.

This guide is for users who are new to making API calls. In this section, you will learn how to:

  • Install the Altitude Python package and authenticate your credentials in a Python notebook environment.
  • Define your query parameters and run an API call using the client.do() function.
  • Export the results as a CSV file.

This guide uses the getRoadSegments query as a working example to return all road segments in Clark County, Nevada.

Note:

If you run into any issues during this process, contact Altitude Support for assistance.

What is an API?

An Application Programming Interface, or API, allows different systems to exchange data without needing to know how the other system works.

For example, a flight-price app does not operate its own fleet of planes, it sends requests to the APIs of United, Delta, and American Airlines, receives their price data, and displays it in their flight-price app.

The Altitude API accepts requests that describe the data you want and returns a structured dataset you can work with directly.

Understanding the client.do() function

When you authenticate with Altitude during your initial setup, the Geotab Altitude Python package creates an object called client. This object represents your active connection to the API.

Calling client.do() tells your connection to send a query to Altitude and return the results. You define the parameters for the data that you need, while client.do() It handles session management, authentication, querying, and the data extraction call.

Setting up your Python notebook environment

Install the Altitude Python package and authenticate your credentials to prepare your notebook environment for API calls.

Before you begin, ensure you have the following:

  • An Altitude account. Your username, password, database name, and server were provided in your Altitude welcome email.
  • A notebook environment. You can use Google Colab or you can launch a Jupyter notebook locally. Altitude provides a pre-configured Python API notebook in Google Colab, open it and select File > Save a copy in Drive to get your own working copy.
  1. Install the Altitude Python package. In a new notebook cell, enter the following command and run the cell:
    !pip install mygeotab
  2. Import AltitudeAPI and create a client object with your Altitude credentials. Copy and paste the snippet into your notebook, fill out your credentials, and press the enter key.
    from mygeotab.altitude import AltitudeAPI
import pandas as pd

client = AltitudeAPI(
    username="you@yourcompany.com",
    password="your_password",
    database="your_database_name",
    server="my.geotab.com"
)
  3. Authenticate your session by calling client.authenticate().
    client.authenticate()
print("Authenticated successfully.")
    Note: If you encounter an authentication error during in your session, re-run client.authenticate().

The client object holds your active session and is ready to use for API calls with client.do(). Keep it available throughout your notebook session.

Running your first API call

Use the Altitude API Guide to identify the values your client.do() call requires, then run the call to retrieve your dataset.

Every client.do() call requires two values that tell the API what data to return:

  • serviceName — which of the five Altitude service modules owns the query
  • queryType — the specific operation within that module

The Altitude API Guide documents both values for every available query, along with the required and optional parameters that go inside functionParameters. In the following example, we use getRoadSegments to return all road segments in Clark County, Nevada.

  1. In the API Guide, find the getRoadSegments entry under the General module and note its serviceName.

    Because getRoadSegments belongs to the General module, the serviceName is dna-altitude-general. Each module has its own dedicated serviceName — using the wrong one will return an error. The guide entry also lists every parameter the query accepts, including which are required.

  2. In a new notebook cell, define your parameters and call client.do().

    For the Clark County example, the call retrieves motorway and primary road segments as of January 2025, filtered to Clark County, Nevada (zone ID 32003), with results returned in imperial units:

    api_params = {
    "serviceName": "dna-altitude-general",
    "functionParameters": {
        "queryType": "getRoadSegments",
        "asOfDate": "2025-01-01",
        "excludeServiceRoads": False,
        "isMetric": False,
        "roadTypes": ["motorway", "primary"],
        "zones": [{"ZoneId": "32003", "ISO_3166_2": "US-NV", "ZoneType": "County"}]
    }
}

api_results = client.do(api_params)

    To adapt this for your own query, replace serviceName and queryType with the values from your API Guide entry, and update functionParameters to match the parameters that query requires.

    Note: The time to return results depends on the size and complexity of your dataset. client.do() handles polling automatically and returns all results when complete.

api_results contains the dataset as a list of rows, ready to use in your notebook. For zone code reference, see Zone Parameters in the Data Dictionary.

Exporting the Results

Collect the data from your API call and export it from the Python Notebook environment as a CSV file.

Once client.do() returns results, convert them to a pandas DataFrame to organize the data into a table, then export it as a CSV file you can open in Google Sheets, Excel, or any other tool.
  1. In a new notebook cell, convert the results to a DataFrame and display the table.
    df = pd.DataFrame(api_results)
print(df.head())
    This organizes the dataset into a table with column headers. Review the output to confirm the data looks correct before exporting.
  2. In the next cell, export the DataFrame to a CSV file.
    df.to_csv('SavedRoadSegments.csv', index=False)
    Replace SavedRoadSegments.csv with your preferred filename. The file is saved to the notebook's working directory.
  3. Download the file from your notebook environment.
    • Google Colab: Click the file icon in the left sidebar, locate the CSV file, click the three-dot menu, and select Download.
    • Jupyter Notebook: The file is saved to the directory where you launched Jupyter. Navigate there in your file system to access it.
The dataset has been downloaded as a CSV file. Now, you can open the dataset with Google Sheets or MS Excel, or import it to the software of your choice.
Previous
Next