BXP is to atmospheric exposure data what MP4 is to video — a universal file format and protocol that any system can read, write, and exchange. Owned by nobody. Usable by everyone. Free forever.
Air quality sensors are deployed across thousands of cities, research institutions, and homes. But every device speaks a different format. Every platform uses a proprietary schema. Data cannot move freely between systems — so it doesn't.
BXP fixes this. A single open standard for reading, writing, and exchanging atmospheric exposure data — across sensors, servers, SDKs, and research platforms — with built-in health risk scoring, privacy protections, and federated networking.
BXP defines the complete stack: file format, REST API, health risk index, privacy framework, and federated node architecture.
JSON-based container carrying readings, location, quality flags, payload hash for integrity, and HRI score. Machine-readable and human-readable.
Standard endpoints any server can implement. Submit readings, query by geohash, aggregate over time windows, verify integrity.
WHO-derived composite Health Risk Index on a 0–100 scale. Comparable across all agents, locations, and time periods.
SHA-256 hashed person IDs, geohash-5 spatial floor, k≥5 anonymity on aggregates, cryptographic deletion proof.
Any institution can run a node. Nodes interoperate. No central owner. Data sovereignty preserved at the source.
The Python SDK ships with zero required dependencies. Everything else is optional.
# Install (zero required dependencies) # pip install bxp-sdk # once published # pip install bxp-sdk[async] # with async client # Or: copy sdk/python/bxp_sdk.py into your project from bxp_sdk import BXPClient, write_bxp, calculate_risk # ── Calculate HRI without any server ────────────────── risk = calculate_risk(pm25=47.2, no2=31.0, duration="8h", population="sensitive") print(risk["score"]) # 72.4 print(risk["level"]) # HIGH print(risk["advice"]) # Wear N95 outdoors. Close windows. # ── Write a .bxp file ───────────────────────────────── write_bxp("accra_20240101.bxp.json", { "latitude": 5.6037, "longitude": -0.1870, "pm25": 47.2, "no2": 18.3, "temp": 29.0, "durationS": 3600, "indoorOutdoor": "outdoor", }) # ── Submit to a BXP node ────────────────────────────── client = BXPClient("https://your-bxp-node.example.com") result = client.submit(latitude=5.6037, longitude=-0.1870, pm25=47.2) print(result["bxpHri"]) # 61.2 print(result["level"]) # HIGH # ── Async client (requires pip install httpx) ────────── from bxp_sdk import AsyncBXPClient import asyncio async def main(): async with AsyncBXPClient("https://your-bxp-node.example.com") as client: result = await client.submit(latitude=5.6037, longitude=-0.1870, pm25=47.2) asyncio.run(main())
# Check node health curl https://your-node.example.com/bxp/v2/health # Get live air quality for a city curl https://your-node.example.com/bxp/v2/city/accra # Submit a reading (no auth required for anonymous) curl -X POST https://your-node.example.com/bxp/v2/readings \ -H "Content-Type: application/json" \ -d '{ "readings": [{ "latitude": 5.6037, "longitude": -0.1870, "agents": [ {"agentId": "PM2_5", "value": 47.2, "unit": "ug/m3"}, {"agentId": "NO2", "value": 18.3, "unit": "ppb"} ], "durationS": 3600, "indoorOutdoor": "outdoor" }] }' # Register a device (returns a token for authenticated writes) curl -X POST https://your-node.example.com/bxp/v2/devices/register \ -H "Content-Type: application/json" \ -d '{"label": "Rooftop Sensor - Building A"}' # Query readings by geohash with pagination curl "https://your-node.example.com/bxp/v2/readings?geohash=s1v0g&limit=50&offset=0" # Verify a reading's integrity curl https://your-node.example.com/bxp/v2/readings/{reading_id}/verify # Aggregate (k≥5 anonymity enforced) curl "https://your-node.example.com/bxp/v2/locations/s1v0g/aggregate"
# Generate a .bxp file from sensor readings python cli/bxp_cli.py generate \ --pm25 47.2 --no2 18.3 --temp 29 \ --lat 5.6037 --lon -0.1870 \ --output accra.bxp.json # Calculate HRI without writing a file python cli/bxp_cli.py hri --pm25 67.0 --no2 31.0 --duration 24h --population sensitive # Validate a .bxp file against the spec python cli/bxp_cli.py validate accra.bxp.json # Export to CSV or GeoJSON python cli/bxp_cli.py export accra.bxp.json --format csv python cli/bxp_cli.py export accra.bxp.json --format geojson # Submit to a BXP node python cli/bxp_cli.py submit --file accra.bxp.json \ --server https://your-node.example.com # Batch submit a directory of readings python cli/bxp_cli.py batch-submit --dir ./sensor_data/ # Generate a self-contained HTML map python cli/bxp_cli.py map ./sensor_data/ --output city_map.html # Store server URL so you don't repeat it every command python cli/bxp_cli.py config set server https://your-node.example.com python cli/bxp_cli.py server-status
{
"bxpVersion": "2.0",
"deviceUuid": "550e8400-e29b-41d4-a716-446655440000",
"geohash": "s1v0g7k", // precision-7, ~153m resolution
"latitude": 5.6037,
"longitude": -0.1870,
"timestampUs": 1710000000000000, // Unix epoch, microseconds
"durationS": 3600, // 1-hour averaging period
"indoorOutdoor": "outdoor",
"agents": [
{ "agentId": "PM2_5", "value": 47.2, "unit": "ug/m3" },
{ "agentId": "NO2", "value": 18.3, "unit": "ppb" },
{ "agentId": "O3", "value": 24.1, "unit": "ppb" },
{ "agentId": "TEMP", "value": 29.0, "unit": "C" }
],
"quality": {
"flag": "UNVALIDATED",
"confidence": 0.9,
"qcMethod": "bxp-sdk-auto"
},
"bxpHri": 61.2,
"bxpHriLevel": "HIGH",
"payloadHash": "sha256:a4c2e1f8..." // tamper detection
}
Every component is specified, documented, and implemented in the reference server.
.bxp files carry readings, location, quality metadata, and an SHA-256 payload hash for tamper detection. Readable by any JSON parser.From PM2.5 to benzene to mold spores — every atmospheric substance the BXP spec covers, with standardised IDs, units, and WHO thresholds.
BXP_HRI translates complex multi-pollutant data into a single 0–100 score that is comparable across locations, agents, and time.
| Range | Level | Who is at risk |
|---|---|---|
0–20 | CLEAN | No restrictions |
21–40 | MODERATE | Sensitive groups: limit exertion |
41–60 | ELEVATED | Reduce outdoor exertion |
61–75 | HIGH | Wear N95. Close windows. |
76–90 | VERY HIGH | Avoid all outdoor activity |
91–100 | HAZARDOUS | Health emergency |
From sensor hardware through the network to researchers — every step is standardised.
Reference implementations, SDKs, integrations, and tools — all open source, all Apache 2.0.
The reference node runs a public BXP API with live data for 10 global cities, a map view, dashboard, and embeddable widgets. No account required.
BXP is archived on Zenodo with permanent DOIs. Cite the protocol or the reference implementation independently.