---
title: "Historical air quality and satellite-observed smoke"
method: POST
path: "/api/locus-air-quality-history"
tags: ["data", "search", "real-estate", "property", "property-research", "due-diligence", "public-records", "x402", "air-quality", "smoke", "wildfire-smoke", "environmental-due-diligence", "government", "citations", "category:environmental"]
---

# Historical air quality and satellite-observed smoke

`POST /api/locus-air-quality-history`

## Request

- Base URL: `https://api.locus.report`
- URL: `https://api.locus.report/api/locus-air-quality-history`
- Auth: one of:
  - API key in header `PAYMENT-SIGNATURE`
  - API key in header `Authorization`

EPA AQS annual monitors, exact-point NOAA HMS satellite smoke days, and separate CDC county modeled PM2.5 when a year lacks nearby AQS PM2.5. For past air context. Missing mirror years are disclosed, not treated as clean air; no source-fire attribution or property safety finding. npx @velinussage/locus-agent-skill add.

## Request body

- union: US street address or latitude+longitude, plus an optional 1-10 calendar-year lookback and AQS monitor radius. NOAA HMS history is exact point-in-polygon.
  - object
    - `address` string, required: Optional US street address or place; provide instead of latitude+longitude.
    - `latitude` number: Optional decimal latitude; provide with longitude to skip address geocoding.
    - `longitude` number: Optional decimal longitude; provide with latitude to skip address geocoding.
    - `yearsBack` integer: Calendar-year lookback, 1-10 years; default 5. The response discloses which requested years are actually ingested.
    - `radiusKm` integer: Nearby AQS monitor search radius in kilometers; default 50, max 150. HMS smoke uses exact point-in-polygon.
  - object
    - `address` string: Optional US street address or place; provide instead of latitude+longitude.
    - `latitude` number, required: Optional decimal latitude; provide with longitude to skip address geocoding.
    - `longitude` number, required: Optional decimal longitude; provide with latitude to skip address geocoding.
    - `yearsBack` integer: Calendar-year lookback, 1-10 years; default 5. The response discloses which requested years are actually ingested.
    - `radiusKm` integer: Nearby AQS monitor search radius in kilometers; default 50, max 150. HMS smoke uses exact point-in-polygon.

## Response `200`

Successful paid artifact, or a free pre-charge diagnostic when the request is outside current coverage.

- object: A cited history artifact with separate AQS monitor, NOAA HMS smoke-polygon, and CDC modeled-gap-fill components; includes available mirror years and charged:false when no substantive source resolves.
  - `kind` 'air_quality_history', required
  - `generatedAt` string, required
  - `point` object, required
    - `latitude` number, required
    - `longitude` number, required
  - `period` object, required
    - `startYear` integer, required
    - `endYear` integer, required
    - `requestedYears` integer[], required
  - `searchRadiusKm` number, required
  - `componentStatus` object[], required
    - `component` 'aqs_monitors' | 'hms_smoke' | 'cdc_gap_fill', required
    - `status` 'ok' | 'no_data' | 'not_needed' | 'not_ingested' | 'source_unavailable', required
    - `detail` string
  - `aqs` object, required
    - `annualMonitorSummaries` object[], required
      - `recordId` string, required
      - `year` integer, required
      - `siteId` string, required
      - `siteName` string
      - `parameterCode` string, required
      - `parameter` string, required
      - `poc` string, required
      - `sampleDuration` string
      - `pollutantStandard` string, required
      - `metricUsed` string
      - `methodName` string
      - `units` string, required
      - `distanceKm` number, required
      - `observationCount` number
      - `observationPercent` number
      - `validDayCount` number
      - `arithmeticMean` number
      - `firstMaxValue` number
      - `firstMaxAt` string
      - `ninetyEighthPercentile` number
      - `ninetyNinthPercentile` number
      - `certificationIndicator` string
      - `eventType` string
    - `availableYears` integer[], required
    - `provenance` object, required
      - `sourceName` string, required
      - `sourceUrl` string, uri, required
      - `datasetPage` string, uri, required
      - `fetchedAt` string
      - `syncedAt` string
      - `license` string
  - `hmsSmoke` object, required
    - `annualSummaries` object[], required
      - `year` integer, required
      - `observedDays` integer, required
      - `polygonCount` integer, required
      - `densityDays` object, required
        - `light` integer, required
        - `medium` integer, required
        - `heavy` integer, required
        - `unknown` integer, required
    - `observedDates` string[], required
    - `availableYears` integer[], required
    - `provenance` object, required
      - `sourceName` string, required
      - `sourceUrl` string, uri, required
      - `datasetPage` string, uri, required
      - `fetchedAt` string
      - `syncedAt` string
      - `license` string
  - `cdcGapFill` object, required
    - `modeledAnnualPm25` object[], required
      - `year` integer, required
      - `countyFips5` string, required
      - `countyName` string, required
      - `meanPredictedUgM3` number
      - `medianPredictedUgM3` number
      - `populationWeightedPredictedUgM3` number
    - `filledYears` integer[], required
    - `provenance` object, required
      - `sourceName` string, required
      - `sourceUrl` string, uri, required
      - `datasetPage` string, uri, required
      - `fetchedAt` string
      - `syncedAt` string
      - `license` string
  - `charged` boolean
  - `caveats` string[], required

## Other responses

- `400`: Invalid request body.
- `402`: Payment Required. For x402 v2, repeat the identical request with a valid PAYMENT-SIGNATURE header (legacy X-PAYMENT is accepted for compatibility), or use Authorization: Payment for MPP Tempo when advertised in x-payment-info.offers.

---

[API](https://skmtc.dev/locus/apis/locus-api.md) · [All operations](https://skmtc.dev/locus/apis/locus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/locus/apis/locus-api/revisions/ba7786b74adb?raw)