Municipal operations teams increasingly recognize air quality as a critical data layer — not just an environmental metric but an operational input that should influence traffic management, event permitting, school operations, and emergency response. But knowing that air quality data is valuable and knowing how to actually integrate it into existing city systems are two different things.
This guide is intended for the technical teams tasked with making that integration happen: city IT departments, smart city platform engineers, and the vendors who build municipal management systems. We'll walk through the Trace AQ REST API from initial authentication through webhook-based alerting and dashboard visualization.
Authentication and Access
The Trace AQ API uses API key authentication passed in the Authorization header. After registering and receiving your API key from the developer portal, all requests follow the same basic structure. The base URL is api.traceaq.io/v2. All responses are JSON. Rate limits depend on your subscription tier; most municipal deployments use our Professional tier, which allows 1,000 requests per minute.
A basic current conditions request looks like this. Set the Authorization header to your Bearer token, then send a GET request to /current with parameters for latitude, longitude, and the pollutants you want. The response returns an object containing AQI, individual pollutant concentrations in µg/m³ or ppb depending on the pollutant, a health advisory string, and data source metadata.
For city operations, you'll typically want to query multiple locations on a regular polling interval. We recommend using our batch endpoint rather than making individual requests for each location. The batch endpoint accepts a JSON array of lat/lon pairs and returns results for all locations in a single response, dramatically reducing API call overhead for deployments monitoring dozens or hundreds of points across a city.
Forecast Data for Operational Planning
The forecast endpoint is where Trace AQ provides the most unique value for city operations. Sending a GET request to /forecast with a location and a horizon parameter (24, 48, or 96 hours) returns hourly forecast values for AQI and each tracked pollutant over that period.
For a smart city dashboard, we recommend requesting 48-hour forecasts on a 30-minute refresh cycle. This keeps your data fresh enough to catch rapidly developing situations while staying well within rate limits. The forecast response includes a confidence interval for each hourly value, which you can use to trigger more cautious thresholds during high-uncertainty periods.
A practical integration pattern: on each refresh, check whether any forecast value in the next 24 hours exceeds your configured alert threshold. If it does, push a notification to the relevant city department alert system. We've seen cities configure different thresholds for different use cases — a lower threshold triggers school advisory preparation, a higher threshold triggers the emergency management team, and the highest threshold activates the full public advisory protocol.
Webhook-Based Alerting
For time-critical alerting, polling is suboptimal because alert latency is limited by your polling interval. Trace AQ supports webhook delivery of forecast threshold events: you register a webhook URL with your alert configurations, and we push an HTTP POST to your endpoint within five minutes of a forecast update that crosses a configured threshold.
Webhook payloads include the location, the pollutant and concentration that triggered the threshold, the forecasted peak value and timing, and a severity classification. Your receiving endpoint should return a 200 response to acknowledge receipt. We implement exponential backoff retry logic if your endpoint is temporarily unavailable.
We recommend running a small buffer service in front of your alert dispatch system that deduplicates webhook events — the same threshold crossing can trigger multiple webhook deliveries during a forecast update cycle, and you generally want to notify your team once, not three times within a few minutes.
Dashboard Visualization
For front-end visualization, the Trace AQ API returns enough data to drive a variety of map and chart components. The most common smart city dashboard pattern we see combines a choropleth map showing current AQI by neighborhood zone with a time series chart showing the 48-hour forecast for the currently selected zone.
The API's GeoJSON endpoint returns forecast data in a format directly consumable by Leaflet, Mapbox, or Deck.gl without transformation. The pollutant timeseries data maps directly to chart.js or D3 time series components. For teams building on Python or Node.js, our SDKs wrap these API calls with async/await support and include example dashboard components.
Production Considerations
A few operational points worth noting before you go live. First, cache aggressively. Air quality conditions don't change every second, and caching API responses client-side for 5–10 minutes significantly improves dashboard responsiveness without sacrificing data freshness. Second, implement graceful degradation for API unavailability. Cities need their operational dashboards to work even when third-party APIs have outages. Store the last successful response and display it with a "last updated" timestamp rather than showing an error state. Third, log all threshold alert events with their forecast basis. When city leadership asks why outdoor activities were cancelled, you want a clean audit trail showing exactly what the forecast said and when.
Our solutions engineering team is available to walk through integration specifics for your city's particular technology stack. Most municipal integrations go from API key to working dashboard in two to four weeks of part-time engineering effort.
