noisycity

Planning repository. No code, no running service — a blueprint.

This repo designs the back end for a volunteer-run urban noise monitoring station: how a small sensor on a private balcony gets its readings out of the owner's house and into a public, documented, machine-readable API that anyone can consume.

noisycity.org is a placeholder domain used throughout for concrete examples (https://noisycity.org/api/v1/...). Nothing is registered and nothing is deployed. Substituting a real host is a find-and-replace.

The hardware half of the project is planned separately in danielrosehill/esp32-porch-decibel-monitor — an ESP32 + I2S MEMS microphone + particulate sensor + accelerometer build, at roughly $80 in parts. This repo starts where that one stops: the station works, it's on the network, the readings are good. Now what?

---

Why this exists

If you own a weather station, contributing your data to a public network is a solved, five-minute problem — Weather Underground, Netatmo, WOW, the PWS networks. Air quality is nearly as easy: Sensor.Community and OpenAQ have turnkey ingest and well-documented public APIs, and a Sensor.Community node is a documented BOM you can order in an afternoon.

Urban noise has no equivalent that is both open and alive. The projects that exist are academic pilots, smartphone-based participatory campaigns, or single- city research deployments — good work, mostly finished, and mostly not designed for someone who wants to leave a permanent calibrated box on a balcony and have its data land somewhere useful. docs/landscape.md is the survey behind that claim, including the honourable exception (Sensor.Community's DNMS) and why it doesn't fully close the gap.

So the practical question this repo answers is: if you were going to build the missing thing, what shape would the data be?

The concrete case

A residential construction site in Jerusalem, in its excavation phase. Rock drilling that is felt as much as heard, fine dust across the balcony, and working hours whose legal boundaries are — to the neighbours — entirely undocumented. Nobody living next to it can answer the two questions that actually matter: how bad is it, in numbers? and when does it end?

That second question is the one this project has an opinion about. See docs/position-permit-transparency.md — stated up front so a reader can discount it as they see fit.

Documents

File	Contents
docs/concept.md	The idea in full: goals, non-goals, who the data is for, what success looks like
docs/architecture.md	Station → Home Assistant + publisher container → public API. Two independent sinks, and why
docs/data-model.md	Entities (Station, Instrument, Datastream, Reading, Aggregate, Correlation, Event) and the parameter vocabulary
docs/api.md	Every endpoint, with request/response examples — readings, computed aggregates, correlations, /about
docs/metrics-and-standards.md	What LAeq/LAmax/L90/Lden actually mean, PM and PPV conventions, and which standards the field names borrow from
docs/landscape.md	Research: existing citizen noise/AQ projects, what each does, current status, what's reusable
docs/position-permit-transparency.md	The advocacy position — construction noise permits should be time-bounded and publicly queryable
docs/privacy-and-licensing.md	No audio ever leaves the device; location fuzzing; proposed data licence
docs/open-questions.md	Decisions deliberately not made yet
spec/openapi.yaml	OpenAPI 3.1 description of the whole surface
examples/	Realistic JSON payloads for every endpoint — the fastest way to see the design
blueprint.typ / blueprint.pdf	The whole thing as one shareable document

The API in one screen

Base URL https://noisycity.org/api/v1. Read endpoints are public and unauthenticated; the ingest endpoint is not.

GET  /about                                  service, operator, licence
GET  /parameters                             parameter dictionary + units
GET  /stations                               all stations (bbox/near/active filters)
GET  /stations/{id}                          one station record
GET  /stations/{id}/about                    siting, photos, equipment[], calibration
GET  /stations/{id}/readings/latest          most recent value per datastream
GET  /stations/{id}/readings                 raw time series
GET  /stations/{id}/summary/{hourly|daily}   computed aggregates
GET  /stations/{id}/correlations             noise ↔ vibration ↔ PM, with lags
GET  /stations/{id}/events                   exceedances and out-of-hours activity
GET  /permits                                proposed — see the position paper
POST /ingest/{id}/readings                   station publisher → API (authenticated)

The three things worth arguing about, all covered in docs/api.md:

1. Raw readings and computed variables are separate resources. /readings is what the box measured; /summary is what the server derived. Different cache lifetimes, different trust levels, different failure modes.
2. /about is a first-class endpoint, not a footnote. Environmental data from an uncertified station is only as useful as its provenance. Mounting height, orientation, the acoustic vent, the calibration date, photographs of the actual install, and a machine-readable equipment[] array — otherwise a number in dB(A) is a number without a meaning.
3. Correlation is a published product, not an exercise for the reader. The whole reason for putting a microphone, a dust sensor and an accelerometer in one box is that construction impact shows up in all three at once. The API ships the cross-correlations and lags directly.

Status

• Landscape research — what already exists and where the gap is (2026-07-25)
• Architecture: two-sink design, station → HA + publisher → public API (2026-07-25)
• Data model, parameter vocabulary, full endpoint design (2026-07-25)
• OpenAPI 3.1 spec + worked example payloads (2026-07-25)
• Position paper on construction permit transparency (2026-07-25)
• Build and site the station — see the hardware repo
• Reference implementation of the publisher container
• Decide whether to run a service at all, or contribute the schema upstream to Sensor.Community / an OGC SensorThings deployment
• Find out who actually wants this data — municipality, researchers, residents' associations, journalists

Licence

MIT for the documents and schema. See docs/privacy-and-licensing.md for the proposed licence on the measurements themselves, which is a separate question.