Making an API Request

Make requests to the Altitude REST API using the Python SDK, TypeScript SDK, or direct HTTP calls.

Overview

The Altitude API is RESTful. Each analytical module has dedicated endpoints under https://altitudeapis.geotab.com/api/v2/. The legacy GetAltitudeData method with serviceName, functionName, and queryType parameters is no longer used.

All requests are authenticated with an API key passed in the Authorization header. Parameters are case-sensitive. Altitude data has a 4-day latency.

Note:

If you are new to working with APIs, refer to the beginner guide in the Altitude API Guide FAQ.

API Workflow

Understand the three-step async pattern used by most Altitude analytical endpoints: submit a job, then poll for results.

Most Altitude analytical APIs are asynchronous. When you submit a request, the API queues a job and returns a job ID immediately. You then poll a second endpoint to check the status and retrieve results when the job is complete.

Every request is validated before processing:

Authentication: the API key is validated on every request.
Authorization and license check: the database's permissions are checked for geography, module, and date range against the requested data.
Job submission: if all checks pass, the job is queued and a job ID is returned.

Note:

Some endpoints enforce a lower hourly rate limit than the default, as low as 5 calls per hour per user. See Rate Limiting for the current limits before designing a workflow that depends on frequent calls to a specific endpoint.

Step 1: Submit your job

Submit a job with POST /api/v2/{endpoint}.

Pass your analysis parameters in the request body. The API returns 202 Accepted with a job body containing an id and a links.self URL to poll.

Step 2: Poll for results

Poll for results with GET /api/v2/jobs/{id}.

The endpoint returns 200. Check the status field to determine whether the job is complete.


Status	Meaning
`PENDING`	Job received, not yet queued.
`QUEUED`	Job queued, waiting to run.
`RUNNING`	Job is actively processing.
`DONE`	Job complete. Results available at `links.result`.
`FAILED`	Job failed. See `error` field for details (RFC 7807 format).
`CANCELED`	Job was cancelled.

Step 3: Fetch results

When status is DONE, use the URL in links.result to retrieve your data.

For all possible status values, see API Workflow.

Canceling a job

To cancel a running job, send DELETE /api/v2/jobs/{id} (SDK: client.jobs.cancel_job(job_id)). The API returns 202 Accepted.

Poll GET /api/v2/jobs/{id} to confirm the CANCELED status.

Choose your approach

Select the method that best fits your workflow:

Python SDK: recommended for Python users. Handles authentication, job submission, polling, and result extraction automatically. See Making an API Request with the Altitude Python Package.
Direct REST: use any HTTP client to call endpoints directly. See Making an API Request with a POST Request.

Making an API Request with the Altitude Python Package

Use the altitude-sdk Python package to run API requests without managing authentication, job submission, or polling manually.

The altitude-sdk package wraps authentication, job submission, polling, and result extraction into typed domain methods. Install it and pass your API key to get started.

Setting up the client

Install the package and initialise the client with your API key:

pip install altitude-sdk

from altitude_sdk import AltitudeClient

client = AltitudeClient(api_key="YOUR_API_KEY")

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

Making a request

Each analytical module is available as a typed domain method on the client. Pass your parameters as a dictionary and call .all() to submit the job and block until results are returned:

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

results = client.stop_analytics.rda(params).all()

.all() is a blocking method - it waits for the entire job to complete before returning. If you need to run multiple jobs concurrently, use .run() to submit and poll manually instead.

Running multiple jobs concurrently

To submit multiple jobs without blocking on each one, use .run() to start each job, then poll with client.jobs.get_job_status(job_id) and retrieve results when done:

import time

job = client.stop_analytics.rda(params).run()
job_id = job.id

while True:
    status = client.jobs.get_job_status(job_id).status
    if status == "DONE":
        break
    if status in ("FAILED", "CANCELED"):
        raise Exception(f"Job ended with status: {status}")
    time.sleep(5)

results = job.results()

For all possible status values, see API Workflow.

Canceling a job

To cancel a running job, call:

client.jobs.cancel_job(job_id)

This sends DELETE /api/v2/jobs/{id} and returns 202 Accepted. Poll GET /api/v2/jobs/{id} to confirm the CANCELED status.

SDK method names

Each API endpoint page in the Altitude API Guide shows the corresponding Python SDK method name. For full examples, see the altitude-python-sdk GitLab repository.

Making an API Request with a POST Request

Call Altitude REST endpoints directly using any HTTP client.

Base URL

All Altitude REST endpoints are served from:

https://altitudeapis.geotab.com/api/v2/

Authentication

Pass your API key in the Authorization header of every request:

Authorization: Bearer <your-api-key>

To generate an API key, see Getting Altitude Credentials.

Step 1: Sending a job submission

Send a POST request to the module endpoint with your analysis parameters in the request body:

POST https://altitudeapis.geotab.com/api/v2/{endpoint}
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "dateRanges": [{"dateFrom": "2025-01-01", "dateTo": "2025-03-31"}],
  "isMetric": false,
  "zones": [{"code": "32003", "iso_3166_2": "US-NV", "type": "County"}]
}

The API returns 202 Accepted with a job body containing an id, a links.self URL to poll, and a links.result URL where results will be available once the job completes:

{
  "id": "its_1719345600000_abc1234def567",
  "status": "PENDING",
  "links": {
    "self": "/api/v2/jobs/its_1719345600000_abc1234def567",
    "result": "/api/v2/{endpoint}/its_1719345600000_abc1234def567"
  }
}

Step 2: Check job status

Send a GET request to /api/v2/jobs/{id} until status is DONE:

GET https://altitudeapis.geotab.com/api/v2/jobs/its_1719345600000_abc1234def567
Authorization: Bearer <your-api-key>

Poll until status is DONE. The endpoint returns 200 with the job body while the job is running. When DONE, the links.result URL contains the results:

{
  "id": "its_1719345600000_abc1234def567",
  "status": "DONE",
  "links": {
    "self": "/api/v2/jobs/its_1719345600000_abc1234def567",
    "result": "/api/v2/{endpoint}/{id}"
  },
  "error": null
}

For all possible status values, see API Workflow.

Step 3: Retrieve results

Call the results endpoint using the URL from links.result:

GET /api/v2/{module}/{id}
Authorization: Bearer <api_key>

Results are paginated. Use the resultsLimit parameter and pagination tokens to retrieve large datasets. See Input/Output Limitations for details.

Canceling a job

To cancel a running job, send a DELETE request to /api/v2/jobs/{id}. Returns 202 Accepted - poll GET /api/v2/jobs/{id} to confirm CANCELED status.

Retrying failed requests

Treat the following HTTP status codes as retryable, since they typically indicate a transient condition rather than a problem with the request itself:

429 Too Many Requests: you have exceeded a rate limit. See Rate Limiting for the response headers to use when timing a retry.
502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout: the service is temporarily unavailable.

Do not retry 4xx responses other than 429. These indicate a problem with the request, such as invalid parameters or an expired API key, and will fail again unless the request is corrected.

For retryable errors, use an exponential backoff: wait before retrying, and increase the wait time after each subsequent failure, up to a reasonable maximum. Add a small random jitter to avoid multiple clients retrying at the same instant.