Official Python SDK for the HVAKR API - HVAC load calculation and building analysis.
pip install hvakrfrom hvakr import HVAKRClient
# Initialize the client
client = HVAKRClient(access_token="your-access-token")
# List all projects
projects = client.list_projects()
for project in projects.projects:
print(project.id, project.name)
# Get a specific project
project = client.get_project("project-id")
print(project.name)
# Get expanded project with all subcollections
expanded = client.get_project("project-id", expand=True)
print(expanded.spaces)The SDK also provides an async client for use with asyncio:
import asyncio
from hvakr import AsyncHVAKRClient
async def main():
async with AsyncHVAKRClient(access_token="your-access-token") as client:
projects = await client.list_projects()
print(projects)
asyncio.run(main())Both clients provide the same methods. The async client methods are coroutines that must be awaited.
HVAKRClient(
access_token: str,
base_url: str = "https://api.hvakr.com",
version: str = "v0",
timeout: float = 30.0,
)access_token: Your HVAKR API access tokenbase_url: API base URL (default: "https://api.hvakr.com")version: API version (default: "v0")timeout: Request timeout in seconds (default: 30.0)
List projects using the v0.6 paginated endpoint. Pass next_cursor as cursor
while has_more is true.
page = client.list_projects(limit=50, search="office", project_type="commercial")
for project in page.projects:
print(project.id, project.name)Retrieve a project by ID.
# Get basic project data
project = client.get_project("project-id")
# Get expanded project with all subcollections
expanded = client.get_project("project-id", expand=True)Create a new project.
result = client.create_project({
"name": "My New Project",
"address": "123 Main St",
"latitude": 40.7128,
"longitude": -74.0060,
})
# `equipmentModes` can be omitted; the API seeds cooling_mode and heating_mode.Update an existing project.
result = client.update_project("project-id", {
"name": "Updated Project Name",
})Delete a project.
result = client.delete_project("project-id")Run the calculator once and retrieve selected sections. Calculation airflows, checksums, and equipment results are keyed by the project's equipment mode IDs.
calculations = client.get_project_calculations(
"project-id", include=["loads", "airflows", "equipment"]
)
cooling_airflows = calculations.airflows.project.by_mode["cooling_mode"]# Start a report, auto-group, check, or auto-takeoff job.
job = client.create_job("project-id", {"type": "check"})
job = client.get_job("project-id", job.job_id)
# Browse the product catalog and inspect the authenticated account.
products = client.list_products(search="fan")
identity = client.me()This SDK follows the breaking HVAKR v0.6 API:
- Use
system.equipmentConfigandzone.equipmentConfiginstead of the legacy central/terminal configuration fields. Components are ordered incomponentsand configured per mode incomponentConfigsByMode. - Use
project.equipmentModesand mode keys such ascooling_moderather than fixed cooling/heating output paths. - Replace flat space airflow fields with
designAirflowsByMode, and place ventilation/infiltration overrides underairflowRequirementsByLoadCondition. get_project_outputs, weather-station methods, and Revit payload options were removed by the platform. Useget_project_calculationsand project jobs.
The SDK raises HVAKRClientError for API errors:
from hvakr import HVAKRClient, HVAKRClientError
client = HVAKRClient(access_token="your-token")
try:
project = client.get_project("invalid-id")
except HVAKRClientError as e:
print(f"Error {e.status_code}: {e.message}")
print(f"Details: {e.metadata}")The SDK is fully typed and exports Pydantic models for all API responses:
from hvakr import (
HVAKRClient,
Project,
ExpandedProject,
)
client = HVAKRClient(access_token="your-token")
# Type hints work with IDE autocompletion
project: Project = client.get_project("project-id")
expanded: ExpandedProject = client.get_project("project-id", expand=True)Both clients support context manager protocol for automatic cleanup:
# Sync client
with HVAKRClient(access_token="your-token") as client:
projects = client.list_projects()
# Async client
async with AsyncHVAKRClient(access_token="your-token") as client:
projects = await client.list_projects()# Clone the repository
git clone https://github.com/flowcircuits/hvakr-python.git
cd hvakr-python
# Install dependencies
pip install -e ".[dev]"# Run unit tests
pytest
# Run with coverage
pytest --cov=hvakr
# Run integration tests (requires HVAKR_API_TOKEN)
# Option 1: Use a .env file (recommended)
cp .env.example .env
# Edit .env and add your HVAKR_API_TOKEN
pytest -m integration
# Option 2: Set inline
HVAKR_API_TOKEN=your-token pytest -m integrationmypy src/hvakrruff check src tests
ruff format src testsMIT License - see LICENSE for details.