AirAgora method · rule airagora-1.1.0
How AirAgora chooses a practical time outside
AirAgora answers one limited question: which complete practical two-hour window in the available forecast has the lowest deterministic severity score? It does not calculate a universal safe time or replace official guidance.
Complete window · 70/30 rule
Mean + worst hour, stable ties
Inputs arrive through one guarded provider adapter
Production is configured only for HTTPS api.openweathermap.org with a server-only OPENWEATHER_API_KEY. The server requests current and forecast pollutant concentrations plus OpenWeather’s official 1–5 provider value and timestamps. The key never enters browser code.
If the key is absent, the host is unexpected, the mode is a fixture or evaluation adapter, or the payload is invalid, production fails closed. Bounded stale cache preserves the original source timestamp and stale label.
The provider scale stays separate from internal severity
Every live result preserves OpenWeather’s official 1–5 value and category for display. AirAgora never labels that value U.S. AQI, European AQI, or a local regulatory AQI.
For ranking, each supported pollutant concentration is mapped continuously within OpenWeather’s documented bands. The resulting 0–1 severity is internal only and is not presented as an official index.
Candidate windows are complete and local-time aware
The engine considers consecutive two-hour periods whose local start is between 06:00 and 22:00. Both hours need valid concentration-derived component severity. Missing hours are not interpolated, duplicated, or treated as clean air.
Timestamps remain absolute until they are formatted in the city’s IANA timezone. That keeps spring-forward and fall-back transitions deterministic: repeated clock labels remain separate instants, while nonexistent local times are not invented.
The 70/30 score keeps the worst hour visible
For each candidate, AirAgora calculates 70 percent of the mean normalized severity plus 30 percent of the worst-hour normalized severity. A pure average could hide a sharp deterioration; a pure maximum could ignore the rest of the period. The fixed blend is simple enough to inspect and explain.
Lower is preferable. Scores within 0.02 are treated as materially tied, and the earlier window wins. The stable ordering prevents repeated requests from jumping between effectively equal periods.
| Rule | Value | Purpose |
|---|---|---|
| Window length | 2 complete hours | Useful planning period |
| Practical starts | 06:00–22:00 local | Avoid impractical overnight winners |
| Score | 70% mean + 30% worst hour | Balance typical and peak severity |
| Tie threshold | 0.02 | Prefer earlier materially equal period |
| Meaningful change | 0.08 | Avoid false precision |
A best window must be meaningfully different
The best score is compared with the median candidate. If the improvement is less than 0.08, AirAgora says conditions remain broadly similar rather than promoting a precise winner. This rule is a product heuristic and is stored with the rule version.
When every eligible window reaches the internal poor band derived from the provider’s pollutant thresholds, the result is “least polluted available window.” It is never relabeled as good or safe merely because it ranks first.
Pollutants, activities, and recorded context
The main pollutant comes from continuous severity derived separately for each pollutant’s documented concentration bands, with a stable tie order. Raw concentrations remain displayed with units. Activity and sensitivity alter caution, not ranking.
Every recommendation records rule version airagora-1.1.0, provider scale, derived severity context, source and fetch timestamps, completeness, candidate scores, selected window, main pollutant, warning state, and reason codes.
- No missing-hour interpolation.
- No fixture, scraping, or alternate-provider fallback.
- No direct conversion between incompatible AQIs.
- No universal-safe claim.
- No hidden activity-based reranking.
Direct answers
Frequently asked questions
Why does AirAgora use two-hour windows?
Two hours is the fixed planning unit chosen for a useful outdoor period. Both hours must be complete, which prevents a single attractive point from becoming the whole recommendation.
Why is the score 70% mean and 30% worst hour?
The blend emphasizes the typical period while keeping a sharp deterioration visible. It is a transparent product rule, not an official agency formula.
What happens when two windows are almost tied?
If scores differ by no more than 0.02, the earlier local window wins. This makes repeated results stable without claiming a meaningful difference.
What if the whole day is poor?
AirAgora labels the least polluted available window and keeps caution visible. It does not call that period good or safe.
Does selecting running change the best window?
No. Activity changes caution wording and thresholds but not the deterministic ranking of candidate windows.
How does AirAgora handle daylight saving time?
It evaluates absolute timestamps and formats them in the location’s IANA timezone, so repeated and skipped clock hours are handled without string arithmetic.
Evidence register
Sources and further reading
The links below identify the primary references used on this page. Selection, summary, and presentation are AirAgora modifications.
Keep exploring
AirAgora provides informational planning guidance, not medical advice. Local conditions can differ from modeled forecasts; follow official guidance during severe events.