gaza-geo-sync

Live map positions in ~7 bytes per vehicle — with a JSON fallback, offline-cache friendly, built for the weakest mobile data.

A small TypeScript template/library for syncing live positions (vehicles, couriers, field teams, a rider sharing their location) between a server and a web or mobile client. It was built in Gaza for a transport app used on 2G/EDGE mobile data and crowded Wi-Fi, and it is published here so anyone building for low-bandwidth users can use it.

• ~7.4× smaller map refreshes than gzip'd JSON on a synthetic Gaza fleet (356 B vs 2,630 B for 50 vehicles; 1,913 B vs 14,959 B for 300).
• 8-byte GPS uploads (JSON: 77 B), and ~4× fewer upload requests while a vehicle is parked.
• JSON stays the default. Binary only when the client asks (Accept), so old clients, curl and debugging keep working.
• Same records either way: the client decodes on arrival, so your offline cache and screens do not change.
• Strict decoder: bounds-checked, refuses trailing bytes, fuzz-tested; only ever throws CodecError.
• Zero runtime dependencies. MIT. Includes Claude Code skills and copy-paste templates.

Research write-up: paper (PDF) · paper source · design notes · test report · migration guide · used in Mishwar · built in Gaza

---

Why

A live map polls every 30 seconds for the position of every vehicle. In JSON one position looks like {"id":"cm1x4k2ab0003npyq8vi3ojyf","lat":31.51234567891234,"lon":34.45678912345678,"speed":8.33,"at":"2026-10-06T07:59:41.512Z"} — and gzip barely helps, because random ids, float noise and per-vehicle timestamps do not repeat. What really changed since the last refresh is a few metres and a few seconds. This format sends only that:

1. Quantise coordinates to 1e-5° (≈1.1 m, finer than phone GPS) as 2-byte offsets from the south-west corner of your area.
2. Index, don't repeat: each object gets a small number once; frames carry sorted gaps (1 byte).
3. Ages, not timestamps: whole seconds before the frame's server time (packed with flags in 1 byte).

Details, alternatives (MessagePack, CBOR, Protobuf, FlatBuffers) and where binary does not win: docs/RESEARCH.md.

Two kinds of connectivity: Wi-Fi and the weakest mobile data

The same client works on both, and degrades gracefully between them:

	on Wi-Fi	on 2G/EDGE-class mobile data (high latency, low bandwidth, loss)
fewer bytes	saves data; little time difference	less airtime and fewer TCP round trips — the map updates sooner on big fleets
fewer requests (standing-still throttle)	fewer requests	~4× fewer uploads while parked: fewer radio wake-ups, fewer chances to time out
204 for uploads	—	no response body to wait for
offline cache	—	the map shows the last good copy when a refresh fails
JSON fallback	old clients fine	old clients fine

Measured in headless Chromium behind Linux tc-netem profiles (Wi-Fi, 4G, 3G, EDGE, 3G with 3% loss):