API Request Examples

Code examples for common Altitude API request patterns using the Python SDK.

Note: The code examples in this article use the altitude-sdk Python package. For direct REST calls, see Making an API Request with a POST Request. For the full job submission and polling pattern, see Making analytical API requests.

Installation and authentication

pip install altitude-sdk
from altitude_sdk import AltitudeClient

# Authenticate with your API key
client = AltitudeClient(api_key="your-api-key")

Simple job process method

Most analytical endpoints follow the two-step async pattern. Use .all() to submit, poll to completion, and return all results in one call:

from altitude_sdk import AltitudeClient

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

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

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

Manual control job process method

For more control over polling (such as when running multiple concurrent jobs) drive the workflow step by step. Check for every terminal status — a job can finish as DONE, but it can also end as FAILED or CANCELED. Polling only for DONE causes the loop to run indefinitely if the job fails or is canceled.

import time

wf = client.stop_analytics.rda(params)

wf.run()  # submit the job (non-blocking); sets wf.id

while True:

    status = wf.status()["status"]

    if status == "FAILED":

        raise RuntimeError(f"Job {wf.id} failed")

    if status in ("DONE", "CANCELED"):

        break

    time.sleep(5)

rows = wf.results()  # fetch the results once DONE

Direct API method

Some endpoints return data immediately with no job or polling required:

industries = client.filters.get_industries()
naics = client.filters.get_naics(min_naics_level=2, max_naics_level=2)
vehicle_classes = client.filters.get_vehicle_classes()

Resuming a job by ID

Every job has an ID. Save it to resume the job later without re-running the analysis:

wf = client.stop_analytics.rda(params)
rows = wf.all()
print(wf.id)   # "its_1719345600000_abc1234" - save this

# Later, in a different process:
handle = client.stop_analytics.rda(id="its_1719345600000_abc1234")
if handle.status()["status"] == "DONE":
    rows = handle.results()

Canceling a job

client.jobs.cancel_job("its_1719345600000_abc1234")
Previous
Next