One interoperable protocol and API that connects sensors, applications, researchers, and institutions — so exposure data moves freely between them. Apache 2.0, no gatekeepers.
No account required · Conformance suite included · Python & TypeScript SDKs
A phone sensor, a fixed IoT node, and a reference-grade monitor all produce the same BXP record. Five stages, fully specified, byte-for-byte identical across implementations.
Coordinates resolved to a geohash cell with a documented precision floor.
Source tiered — phone, community, or reference instrument — and classified as native, imported, community, research, or simulated.
Units normalised, quality control applied, corrections recorded separately from raw values.
Privacy enforced: hashed identifiers, coarsened location, k-anonymity for aggregates.
Stored, queryable, and replicable across nodes with an identical response schema.
// human-readable, diffable, spec-referenced { "bxpVersion": "2.0", "source": "native", "location": { "lat": 5.6037, "lon": -0.1870 }, "agents": [ { "agentId": "PM2_5", "value": 47.2, "unit": "ug/m3" }, { "agentId": "NO2", "value": 18.3, "unit": "ug/m3" } ], "bxpHri": 61.2 }
// 32-byte header, CRC32, optional gzip 0x00 magic BXP\0 0x04 version 2.0 0x06 fileType READING 0x08 flags COMPRESSED | DRAFT 0x0C timestamp µs since epoch 0x10 payloadLen 4096 0x14 headerCRC32 ✓ verified 0x18 payloadCRC32 ✓ verified 0x1C payload gzip(JSON)
The reference node ships with a REST API, a dashboard, a map, a validator, and federation endpoints. Deploy it yourself, or point a client at someone else's — the schema does not change.
Experimental BXP-HRI is a composite 0–100 index weighted by WHO disability-adjusted life-year burden data. It is not clinically or epidemiologically validated and must not be used for medical decisions. Methodology is published in full so it can be reviewed and challenged.
Sensors, agencies, and research networks all measure the same atmosphere and all speak incompatible formats. BXP removes the translation layer that every project otherwise rebuilds.
| Capability | Ad-hoc CSV | Vendor API | BXP |
|---|---|---|---|
| Open specification, no vendor lock-in | No | No | Yes — Apache 2.0 |
| Byte-for-byte conformance tests | No | Vendor-only | 17 golden vectors |
| Human-readable and binary forms | CSV only | Usually JSON only | .bxp.json + .bxp |
| Integrity verification built in | No | Varies | CRC32 header + payload |
| Privacy floor enforced by the format | No | No | Hashed IDs, k-anonymity |
| Source provenance carried with data | No | Partial | 5-class taxonomy |
| Federated, no central owner required | No | No | Pull-based /sync |
| Works on a $12 microcontroller | No | No | 32-byte fixed header |
The specification, the golden vectors, and both reference SDKs are public. If your implementation passes the conformance suite, it is BXP 2.0 compliant — that is the whole test.
# pip install bxp-sdk from bxp_sdk import write_bxp, read_bxp, calculate_risk, BXPClient # composite risk from raw sensor values risk = calculate_risk(pm25=67.0, no2=31.0, duration="24h", population="sensitive") print(risk["score"], risk["level"]) # 89.6 VERY_HIGH # write, verify, submit write_bxp("accra.bxp.json", {"latitude": 5.6037, "longitude": -0.1870, "pm25": 47.2, "source": "native"}) print(read_bxp("accra.bxp.json")["_integrityOk"]) # True BXPClient("http://localhost:5000").submit(latitude=5.6037, longitude=-0.1870, pm25=47.2)
// npm install @bxp/sdk import { writeBxp, readBxp, calculateRisk } from '@bxp/sdk'; const risk = calculateRisk({ pm25: 67.0, no2: 31.0, duration: '24h', population: 'sensitive' }); console.log(risk.score, risk.level); // 89.6 'VERY_HIGH' const buf = encodeBxpBinary(record, { compress: true }); console.log(buf.length); // 32-byte header + gzipped payload const back = decodeBxpBinary(buf, { verify: true }); console.log(back.crc32Valid); // true
# submit a reading curl -X POST http://localhost:5000/bxp/v2/readings \ -H "Content-Type: application/json" \ -d '{"readings":[{"latitude":5.6037,"longitude":-0.1870, "source":"native", "agents":[{"agentId":"PM2_5","value":47.2,"unit":"ug/m3"}]}]}' # latest observation for a geohash cell curl http://localhost:5000/bxp/v2/locations/s1v0g/latest # node health curl http://localhost:5000/bxp/v2/health
# generate, validate, and submit without writing code python cli/bxp_cli.py generate --pm25 47.2 --no2 18.3 --lat 5.6037 --lon -0.1870 python cli/bxp_cli.py validate reading.bxp.json python cli/bxp_cli.py hri --pm25 67.0 --no2 31.0 --duration 24h --population sensitive python cli/bxp_cli.py submit --server http://localhost:5000 --file reading.bxp.json python cli/bxp_cli.py map ./readings/ --output map.html
Any implementation that passes the 17 golden vectors is compliant. No certification authority required.
MAJOR changes get 18 months advance notice and dual-version support. MINOR additions are ignored-and-preserved by design.
A 32-byte fixed header and a flat JSON payload keep the codec viable on microcontrollers, not just servers.
Unspecified areas are marked unspecified. Unimplemented features raise rather than silently no-op.
pip install bxp-sdk
# TypeScript: build from the repository
git clone https://github.com/bxpprotocol/bxp-spec
cd bxp-spec/sdk/typescript && npm install && npm run buildThe validator runs entirely in your browser — paste a BXP record, get schema validation, integrity verification, and an HRI breakdown with no server round-trip.
No node has to phone home. Run a BXP node behind your own firewall, federate with peers on demand, and keep every reading under your jurisdiction's data law.
Aggregate low-cost sensor data into a national picture without replacing existing reference monitoring.
Ship a BXP-compliant device and your data is immediately usable by every BXP node in the network.
Query across nodes with one schema instead of writing a parser per data source.
Build dashboards, alerts, and health advisories on a stable contract that will not break under you.
Quantify environmental exposure across sites, supply chains, and portfolios with a documented method.
Run a node for a neighbourhood, a city, or a campaign — and keep the data under community control.
A complete working stack in the repository — not a roadmap. Clone it, run it, extend it.
FastAPI + SQLite server with readings, locations, nearby, sync, dashboard, and metrics.
python · fastapiBuild, validate, encode, decode, and submit. Includes the native binary codec.
pip · 3.9+Byte-for-byte identical binary output to the Python SDK, verified by shared vectors.
npm · node 18+Generate, validate, convert, submit, batch-import, export CSV, and render maps.
python · argparseMQTT bridge for live sensors, plus an OpenAQ v3 importer that preserves source provenance.
mqtt · openaq v317 golden vectors — valid, malformed, truncated, tampered — run against every implementation.
python · typescriptClient-side validation and HRI calculation. Paste a record, get a verdict. Nothing leaves your machine.
static htmlReference consumer app — map your exposure over time from any BXP-compliant node.
static htmlThe full v2.0 document rendered for the web — file format, agents, pipeline, API, privacy, conformance.
referenceAll 23 endpoints with parameters and descriptions, generated from the running server.
openapi 3.1Every atmospheric agent with its canonical unit and the WHO guideline value it is measured against.
31 agentsHow to pin a version so your integration stays valid, plus BibTeX, RIS, APA, MLA, and Chicago with permanent DOIs.
doi · bixtexGovernance, security posture, and known limitations are written down in the repository — including the parts that are not finished yet.
No royalties, no restrictions, no gatekeepers. Anyone can use, modify, or redistribute. Read the license.
Who decides specification changes, through what process, and what is aspirational versus real. Read GOVERNANCE.md.
Attack surfaces, disclosure timeline, secure deployment checklist, and a full list of known limitations stated as limitations. Read SECURITY.md.
Spec and reference implementation each carry a permanent Zenodo DOI, so published research can cite a fixed version. Spec DOI · Implementation DOI.
SHA-256 hashed identifiers, geohash precision floors, k-anonymity for aggregates, and cryptographic deletion — enforced in the reference implementation, not promised in a policy document.
Pull-based replication with cursor pagination and deletion tombstones. No node owns the network, and no operator has to trust a single point of failure.
Clone the reference node, run the conformance suite, or wire up the SDK in an afternoon. Nothing here requires permission, a contract, or a conversation with us.
Questions or an implementation to share? Open a discussion or email bxpprotocol@proton.me.