---
title: "Add-on, air quality for one location"
method: GET
path: "/gauge/air"
tags: ["gauge", "air", "no-data-no-charge", "official-source", "record-hash"]
---

# Add-on, air quality for one location

`GET /gauge/air`

## Request

- Base URL: `https://api.truthbear.co`
- URL: `https://api.truthbear.co/gauge/air`
- Auth: none declared

Add-on, air quality for one location: US AQI category and PM2.5 reading from EPA and CAMS official feeds. Descriptive only, never a forecast or advice. No data -> 422 no_charge, not billed. Every record carries an offline-recomputable record_hash. Also searched as: air quality index; pm2.5 level; city pollution reading; health exposure air.

## Query parameters

- `loc` 'us-stlouis' | 'us-memphis' | 'us-losangeles' | 'us-fresno' | 'us-phoenix' | 'us-denver' | 'us-saltlakecity' | 'us-houston' | 'us-newyork' | 'us-chicago' | 'us-seattle' | 'us-portland', required

## Response `200`

Paid response

- object
  - `nature` string, required: Neutrality statement: GAUGE supplies observations and trend description only - no judgement, no prediction, no recommendation
  - `addon` 'air' | 'precip': Conditional - returned only by the /gauge/air and /gauge/precip sub-endpoints: the add-on line marker
  - `location` string: The location key of this bundle - the ?loc= you passed in
  - `name` string, nullable: Human-readable name of the object
  - `line` string: The line this bundle belongs to (e.g. airquality)
  - `readings` object[], required: CORE DELIVERY of this endpoint: multiple signal readings for the same location. Per-row shape is in items - the single-signal fields live INSIDE items, not at the top level
    - `signal_id` string: Signal id in genus.species ASCII binomial form (e.g. crypto.spot / macro.unemployment / shipping.route-disruption); full list at free /gauge/catalog
    - `entity` string: Monitored object id (e.g. btc / us / hormuz); full list at free /gauge/catalog or /gauge/preview
    - `entity_name` string, nullable: Human-readable name of the object
    - `snapshot_date` string: ISO-8601 date-time in UTC (e.g. 2026-07-24T00:00:00.000Z; aligned to midnight of that day)
    - `observed_at` string: Actual observation time of the data, ISO-8601
    - `data_age_hours` number, nullable: Age frozen at collection time (0 = same hour), for reference only - if a collector stalls this field stops moving. For freshness always use provenance.age_hours_now (computed at request time) and provenance.freshness; the threshold basis is in provenance.freshness_basis
    - `current` object, nullable: Current reading. The inner metric structure varies by signal (crypto -> {price_usd, volume_24h, ...}; shipping -> {wind_kmh, wave_height_m, ...}). Units are carried in the field-name suffix; see also standard_ruler.unit
    - `previous` object, nullable: Previous-period reading (a subset of the metrics in current; or {note} explaining that there is no previous value)
    - `change` object, nullable: Change, nested per metric: change.<metric> = {delta, direction, direction_reason?}, plus the scalar change.period (e.g. "vs_previous"). direction is one of rising/falling/stable/unknown - unknown means the direction CANNOT BE DETERMINED, it does not mean stable; in that case direction_reason carries a machine-readable cause: no-previous-record / metric-absent-in-previous / metric-absent-in-current / non-numeric-value
    - `trend_7d` object[], nullable: Array of the last 7 trend points; [] means this signal has no series yet or the series does not apply - it is not an error
    - `sources` object[], nullable: Source list [{name, value, weight, as_of, role, independent, relay_of?}]. independent:true = confirmed independent source; false = confirmed relay channel of another source (relay_of names the origin); null = independence unconfirmed (neither denied nor claimed). name/weight/independent/relay_of are record_hash core fields, so tampering with an independence claim breaks self-verification; as_of/value/role drift easily and are not hashed
    - `source_agreement_cv` number, nullable: Multi-source agreement, coefficient of variation (smaller = closer agreement). Present ONLY when two or more CONFIRMED-INDEPENDENT sources measure the same fact at the same time - see sources[].independent. Same source relayed through two channels does not count as independent, and two different time bases (daily mean vs spot) do not count as agreement. Single-source / unconfirmed independence / not applicable -> null
    - `standard_ruler` object, nullable: Official standard ruler (band / thresholds / normalized_index / pct_to_action, with unit and provenance); null when the line has no official ruler. Inner structure varies by signal
    - `stat_ruler` object, nullable: Statistical ruler: empirical percentile position across the last 5 same-season years; null when there are no statistics
    - `strata` object, nullable: Statistical strata: share of each official band over the last 5 same-season years plus the band the current value falls in; null when there are no statistics
    - `summary_zh` string, nullable: Human-readable one-line summary, IN CHINESE (zh-TW): reading + where it sits on the official ruler + statistical position. This is the HUMAN front-desk copy - machine consumers should read summary_en (English verdict) instead
    - `lifecycle` object, nullable: Lifecycle block (state / birth_at / end_at / death_type / context). Part of the record_hash v3 core, so offline recomputation must include it; null for non-lifecycle lines
    - `hash_core_version` integer, nullable: Core-contract version of record_hash (currently 3); use it to pick the right core composition when recomputing offline
    - `ots_status` string, nullable: RETIRED FIELD - always "pending" or null; this field is no longer updated and is kept only for older parsers. Anchoring is done per write-batch (previously one root per day): each batch of writes gets a Merkle root stamped via OpenTimestamps, typically confirmed into a Bitcoin block within hours. See GET /gauge/anchor?hash= for the inclusion proof and the block number.
    - `source_ref` string, nullable: Official source URL (provenance)
    - `source_tier` string, nullable: Source tier: T1 (first-hand official) / T2 or T2-<subtype, e.g. T2-exchange> (observable, curated) / screen-viewpoint; null = untiered (see unverified)
    - `record_hash` string, nullable: sha256:<64hex> (contract A v3, binds the values plus provenance)
    - `record_hash_verifiable` object, nullable: {mode:offline|via-endpoint, note}
    - `unverified` boolean: true = the source is untiered (source_tier is null); buyers and agents can filter on this
  - `provenance` object, nullable: Data lineage: {served_from, data_as_of, oldest_leg_as_of, data_age_hours (frozen age, reference only), age_hours_now (age computed at request time - the real basis for freshness), freshness(fresh|recent|stale), freshness_basis (the cadence and threshold used for this row, as a string), dead_source (optional: upstream frozen or discontinued), data_lineage:[{signal,traceable_to,uncertainty,record_hash,...}], validation_status}. Freshness is cadence-aware, so monthly/quarterly/annual official lines are not misjudged against a 24h rule; the same basis is used by free /gauge/coverage. Buyers can trace back to the official source
  - `decision_points` object, nullable: {count, points:[{tag,current,swappable,how}], note} - decision points you can re-run with a swapped tag (one swapped tag = one call); leave it alone and the original context is the default, at no extra charge
  - `note` string: Conditional - endpoint-specific honest disclosure (limits, granularity, disclaimer); some endpoints omit it
  - `grade` string, nullable: Honest data-grade disclosure (e.g. "screening-level, not decision-grade")
  - `scope` string, nullable: Honest statement of scope and limits: monitoring is not forecasting, intelligence is not instruction, and the boundary of what is verifiable
  - `_citation` object, nullable: Offline-verifiable citation: {statement_type, not_advice:bool, claim, fact, source, record_hash, signature(Ed25519), key_id, issuer_DID(did:key), verify_url} - the trust root for zero-trust self-verification

## Other responses

- `402`: Payment Required
- `422`: No data for this query - no_charge:true, you are NOT billed

---

[API](https://skmtc.dev/truthbear/apis/truth-bear-verifiable-screening-intelligence-for-ai-agents-g.md) · [All operations](https://skmtc.dev/truthbear/apis/truth-bear-verifiable-screening-intelligence-for-ai-agents-g/llms.txt) · [OpenAPI document](https://skmtc.dev/truthbear/apis/truth-bear-verifiable-screening-intelligence-for-ai-agents-g/revisions/35744dfa4550?raw)