Making an API Request

Learn how to make API requests using MyGeotab wrappers or direct POST requests, including necessary parameters and authentication details.

Note:

If you are new to working with API calls, refer to our beginner guide in the FAQ.

Every API request requires a serviceName, functionName, queryType, and other functionParameters as needed.

  • The method for all API requests is GetAltitudeData. You will be notified if this changes.
  • The APIs should be called using a POST command.
  • Parameters are case-sensitive.
  • Altitude data has a 4-day latency.
  • All times (timeFrom or timeTo) in the API request should be submitted in the local time according to the region of analysis.

You can make an API request either through MyGeotab's request wrappers, or by sending a POST request to Altitude.

Making an API Request with the Altitude Python Package

Use the client.do() function from the Geotab Altitude Python package to run API requests without managing session tokens, polling, or data extraction manually.

The Geotab Altitude Python package provides a client.do() function that wraps the full API request into a single call. It handles session management, authentication, status polling, and data extraction. You need to define the parameters specific to your query.

This approach is recommended for users working in Python notebook environments such as Google Colab or Jupyter.

Setting up the client

Install the package and authenticate before making API requests:

!pip install mygeotab

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"
)

client.authenticate()

Request structure

Pass a single parameter dictionary to client.do() with two required top-level keys:

  • serviceName — identifies which Altitude service module owns the query.
  • functionParameters — the details of your query, including queryType, isMetric, and any additional parameters the 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.

Refer to the Altitude API Guide for the serviceName and queryType values for each available query, along with all required and optional parameters.

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

api_results = client.do(api_params)

Making an API Request with MyGeotab Request Wrappers

Use any MyGeotab API request wrappers available on Geotab's GitHub.

When calling the authenticate method of these wrappers, you will need to add serverName or server (depends on the wrapper you choose) as a parameter (in the same object that has your userName, database, and password) and set it to “altitudeserver.geotab.com”. After authenticating, you can use your API object to make an API request similar to the following: 


api.call("GetAltitudeData", {
	"serviceName":<serviceName>,
	"functionName":<functionName>,
	"functionParameters":{
		"queryType": <queryType>,
		...otherParams
	}
}, function(result) {
	console.log("Done: ", result);
}, function(e) {
	console.error("Failed:", e);
});

Making an API Request with a POST Request

Pass your credentials to the Altitude server to begin using the Altitude API

Make a POST request to https://altitudeserver.geotab.com/apiv1/ and pass your credentials with every request along with your other parameters.


{
	"method":"GetAltitudeData",
	"params":
	{
		"serviceName": "<serviceName>",
		"functionName": "<functionName>",
		"functionParameters":{
			"queryType": <queryType>,
			...otherParams
	},
	"credentials":{
		"database": "<your database>",
		"sessionId": "<your sessionId>",
		"userName": "<your userName>"
		}
	}
}

Obtaining a SessionId

If you decide to use the second option (make a POST request), first you need to make an authentication API request to get your session Id. You also need to ensure that you include a credentials object with every API request. Use the information received in the Altitude welcome email (username, password, and server name) to make an authentication API request to get a session Id that will be used in all subsequent API requests. Session Ids are valid for two weeks.

Basic Information

FieldValue
URLhttps://altitudeserver.geotab.com/apiv1/
MethodPOST
AuthenticationNone, public

Request Body

ParameterTypeDescription
MethodStringMust equal "Authenticate".
ParamsObjectAn object that contains "database", "userName", "password".
  • database is the database name that you receive when you sign up for the Altitude platform.
  • username is the username that you receive when you sign up for the Altitude platform.
  • password is the password that you set up when you receive the reset password email upon signing up for the Altitude platform.

Responses

CodeTypeDescription
200JSONAn object with your credentials to be used for future API requests.
401/500JSONCan be any of a variety of errors.

Sample Request Body


{
	"method": "Authenticate",
	"params":
	{
		"database": "<your database name>",
		"password": "<your password>",
		"userName": "<your user name>"
	}
}

Sample Response


[{
	"result": {
	"credentials": {
		"database": "<your database name>",
		"sessionId": "<your new session id>",
		"userName": "<your user name>"
	},
	"path": “altitudeserver.geotab.com”
	},
	"jsonrpc": "2.0"
}]