Today we're releasing the Trace AQ Python SDK v2.0, a complete ground-up rewrite that addresses the most significant pain points reported by our developer community over the past year. The short version: everything is async now, WebSocket streaming works, and the query builder is dramatically more intuitive. Here's what changed and why.
Why We Rewrote It
The v1 SDK was written when we were primarily focused on researchers using Jupyter notebooks and batch data pulls. Synchronous HTTP requests made sense for that use case — you're building a dataset, not a real-time application, and blocking on each request is acceptable. But as our customer base expanded to include operations teams building dashboards and alert systems, the synchronous architecture became a real bottleneck.
Developers building real-time applications need to monitor dozens or hundreds of locations simultaneously, process streaming forecast updates as they arrive, and integrate with async application frameworks like FastAPI and Starlette. The v1 SDK required awkward threading workarounds to support these patterns. The v2 SDK makes async the default and first-class design principle throughout.
Async Throughout
Every method in the v2 client is an async coroutine. The client class is initialized with your API key and an optional session configuration. Fetching current conditions for a location is a single await call. Fetching batch data for multiple locations is equally simple — pass a list of location tuples and the SDK handles the concurrent requests and response aggregation for you.
The SDK is built on httpx for HTTP transport, which provides a clean async interface over connection pooling and retry logic. Connection reuse across multiple requests in the same session reduces latency substantially compared to opening a new connection for each request, which was a common source of performance problems in v1 integrations.
For backwards compatibility, we've included a synchronous wrapper that lets existing v1 code run without modification. The wrapper runs the async client in a managed event loop. We recommend migrating to native async at your own pace — the sync wrapper is a compatibility bridge, not a recommended long-term approach.
WebSocket Streaming
The most requested feature in v2 is WebSocket streaming for real-time forecast updates. Rather than polling the REST API on a timer, WebSocket clients maintain a persistent connection and receive pushed updates whenever a new forecast is generated for their subscribed locations.
Subscribing to a location stream is straightforward. Initialize the stream client with your API key, then use an async context manager and async for loop to iterate over incoming messages. Each message is a typed dataclass with the location identifier, a timestamp, the pollutant values, and a change_type field indicating whether this is a routine forecast update or an alert-triggering threshold crossing.
WebSocket connections are automatically reconnected with exponential backoff if they're dropped. Subscriptions are reestablished automatically after reconnection. You don't need to manage connection lifecycle in your application code.
Redesigned Query Builder
The v1 SDK exposed the API parameters directly, which required consulting the API documentation to understand which parameter combinations were valid. The v2 query builder uses a fluent interface that guides you toward valid queries while keeping the code readable.
Building a 48-hour hourly forecast query for a single location now reads clearly in code: create a ForecastQuery, chain .for_location() with the coordinates, .hourly() for the time resolution, and .hours(48) for the window. The query builder validates parameter combinations at construction time and raises descriptive errors for invalid configurations rather than returning cryptic API error responses.
The same builder pattern works for batch queries, historical data pulls, and alert configuration. Consistency across query types was one of the primary design goals for v2.
Migration Guide
If you're upgrading from v1, the main changes to your code are adding async/await keywords to client calls and wrapping your entry point in an async main function. The response data structures are backward compatible — the same attributes that existed in v1 exist in v2, with a few additions for new fields like confidence intervals on forecast values.
Install v2 with pip install "traceaq>=2.0". Full migration documentation and a migration script that automates most of the async conversion work are available in our developer docs.
We're committed to making the Trace AQ API as developer-friendly as possible. If you hit issues with v2 or have feedback on the SDK design, our developer Slack workspace and GitHub issues are both actively monitored by the engineering team.
