AirAware Normalized Data Shape

Core Rule

Every adapter should emit one or more AirAware observations. An observation is a source-attributed fact for a place and time. It can contain one measurement, several measurements from the same instrument, or one alert/event. Raw provider payloads should be retained by reference, not treated as the public contract.

Top-Level Observation

schema_versionVersioned contract for downstream clients.airaware.observation.v1

idStable deterministic ID from source, location, time, and signal.cdc-us-wastewater:site-300:2026-W18

record_typeWhat the record represents.observation, alert, forecast, layer

domainBroad AirAware product domain.wastewater, outdoor_air, indoor_air, wildfire_smoke, weather_alert

signalsOne or more normalized measurements or event attributes.pm2_5, co2, covid_19, grass_pollen

locationPoint, administrative area, site, sewershed, school, business, venue, or geometry reference.Boston school, CDC sewershed, NWS alert zone

timeObserved, valid, forecast, and ingested timestamps.observed_at, valid_from, valid_to

sourceProvider identity, URL, license, adapter version, and access notes.purpleair, cdc-nwss, airspot

qualityConfidence, freshness, QA flags, and whether the reading is raw/modelled/interpolated.observed, modelled, community_sensor

displayHuman-facing labels and severity used by the widget/map.level: moderate, color: #f59e0b

rawPointer to retained raw data or provider identifiers; avoid publishing sensitive raw payloads.raw_ref, provider_record_id

Location Shape

admin1 and admin2 are optional geodata fields for cross-country normalization. In the U.S. they usually mean state/territory and county/county-equivalent. In other countries they can map to province, region, prefecture, district, municipality, or another official administrative level.

labelMain display name.Boston Latin School

sublabelSecondary display text for context.BPS indoor air sensor, Ward 5 sewershed

location_typeControlled category for filtering and icons.school, sewershed, business

countryISO country code when possible.US, CA, JP

admin1First-level administrative area.State, province, region, prefecture

admin2Second-level administrative area.County, district, municipality

addressStructured address block where the source provides one and privacy allows publication.Street, city, postal code, country

contactPublic contact information for places or source owners.Website, phone, email, contact name

lat / lonPoint coordinate, rounded when needed for privacy.42.3601, -71.0589

geometry_refPointer to polygon/line/tile geometry for areas.Sewershed polygon, smoke plume, alert zone

Location Type Vocabulary

admin_areaCountry, state, province, county, city, or official statistical area.Massachusetts, Suffolk County, Brussels

monitoring_siteGeneric instrument or public-health monitoring location.Air monitor, wastewater station, weather station

sewershedWastewater catchment or sewage treatment service area.CDC sewershed, city treatment catchment

watershedNatural hydrologic watershed or basin.River basin, drainage basin

schoolK-12, preschool, university, classroom, campus, or school building.BPS school IAQ site

businessPublic-facing business or commercial venue.Restaurant, salon, shop

public_venueLibrary, museum, theater, government office, transit hub, or public building.Library CO2 reading

healthcareHospital, clinic, pharmacy, or care facility.Clinic indoor air reading

residentialHome or residential community data; usually privacy-reduced.Neighborhood sensor, apartment building aggregate

mobile_sensorWearable, vehicle, or moving sensor path.AirSpot wearable route

alert_areaWarning zone, forecast zone, incident area, or CAP polygon.NWS alert zone, MeteoAlarm region

fire_perimeterWildfire perimeter or active fire area.NIFC perimeter

smoke_plumeSmoke polygon or plume forecast area.NOAA HMS smoke plume

map_tileRaster or vector tile used for heatmap display.Pollen heatmap tile, AQI heatmap tile

unknownTemporary fallback while an adapter is being normalized.Raw source row without clear place type

Signal Shape

{
  "signal": "pm2_5",
  "label": "PM2.5",
  "value": 8.6,
  "unit": "ug/m3",
  "index": {
    "system": "us_epa_aqi",
    "value": 1,
    "category": "Good"
  },
  "level": "low",
  "method": "sensor",
  "basis": "1 hour rolling average"
}

Example Observation

{
  "schema_version": "airaware.observation.v1",
  "id": "airspot:place:example:2026-06-24T13:00:00Z",
  "record_type": "observation",
  "domain": "indoor_air",
  "signals": [
    {
      "signal": "co2",
      "label": "CO2",
      "value": 720,
      "unit": "ppm",
      "level": "low",
      "method": "community_sensor"
    }
  ],
  "location": {
    "label": "Example cafe",
    "sublabel": "Community CO2 reading",
    "country": "US",
    "admin1": "Massachusetts",
    "admin2": "Suffolk County",
    "lat": 42.3601,
    "lon": -71.0589,
    "location_type": "business",
    "address": {
      "street": "1 Example Street",
      "city": "Boston",
      "postal_code": "02108",
      "country": "US"
    },
    "contact": {
      "website": "https://example.org",
      "phone": null,
      "email": null
    },
    "privacy": "public_place"
  },
  "time": {
    "observed_at": "2026-06-24T13:00:00Z",
    "fetched_at": "2026-06-24T13:05:00Z"
  },
  "source": {
    "id": "airspot",
    "name": "AirSpot CO2 Map",
    "url": "https://map.airspothealth.com/data",
    "access": "public_map_review_needed"
  },
  "quality": {
    "confidence": "community",
    "freshness": "current",
    "warnings": []
  },
  "display": {
    "title": "Indoor CO2",
    "level": "low",
    "summary": "CO2 720 ppm"
  }
}

Adapter Expectations

Preserve provider termsLicenses and attribution vary by source.Never strip source name, URL, or access limits.

Normalize unitsMaps need comparable values.Use canonical units in `signals[]`; keep provider units in `raw` if different.

Separate observed vs modelledUsers should know when values come from sensors, forecasts, or interpolation.Use quality.observation_kind.

Support privacy-safe locationsIndoor/community readings may require lower precision.Use approximate coordinates or admin areas where needed.

Keep raw referencesAuditing and reprocessing need traceability.Store raw_ref or provider IDs, not necessarily full raw payloads in public JSON.