Data Normalization

Overview of how the API and MCP tools normalize sensor data for cross-service comparison and LLM-friendly queries.

Overview

Sensors from different providers (Purple Air, AirNow, NDBC) report data in different formats. The API normalizes data so that:

• Temperature from Purple Air (Celsius) and AirNow (often Fahrenheit) both appear as air_temperature_c in celsius
• PM2.5 from Purple Air and AirNow use the same parameter pm2_5_ug_per_m3 and unit µg/m³
• Timestamps are ISO 8601 UTC
• Measurements use a canonical array format: [{parameter, value, unit, unit_original}]

This enables LMs and clients to compare readings across sensors without extra parsing or unit conversion.

Data Types (Sensors and Feeds)

Each sensor and feed has a data_types array listing the canonical parameter IDs it collects.

Examples:

Filtering: Use ?data_types=air_temperature_c,pm2_5_ug_per_m3 to list only sensors that collect those parameters.

Raw vs. Clean Data

Query params: data_format=cleaned or data_format=raw on:

• GET /api/v1/sensors/:id/readings/latest
• GET /api/v1/sensors/:id/readings
• MCP sensor_cleaned_stream argument

Canonical Measurement Format

Cleaned measurements follow:

[
  { "parameter": "air_temperature_c", "value": 22.5, "unit": "celsius", "unit_original": "celsius" },
  { "parameter": "pm2_5_ug_per_m3", "value": 12.3, "unit": "µg/m³", "unit_original": "µg/m³" }
]

Legacy responses may still use a flat object: {"air_temperature_c": 22.5, "pm2_5_ug_per_m3": 12.3}.

Parameter Filter

For time-series readings, use ?parameter=air_temperature_c to return only that parameter in each reading. Comma-separated for multiple: ?parameter=air_temperature_c,pm2_5_ug_per_m3.

Provenance

Readings include provenance for traceability:

{
  "provenance": {
    "sensor_id": "uuid",
    "service_id": "ndbc",
    "source_id": "46108"
  }
}

Common Canonical Parameters