Pothole Reporter
An independent Android app for potholes. Drive uses either the mounted phone camera
or an H.264 RTSP-over-TCP dashcam while the phone shows Maps or a call; one tap on Photo opens the camera for a pothole check and
prepares evidence for an official complaint channel. Reports remain on the phone, and
nothing is filed automatically. There is no project-operated backend or account system.
Current release: v1.38.0
Example detection and current coverage. Map boundary: DataMeet India community, CC0, following the Survey of India standard; no government endorsement. Select either image to enlarge.
Coverage
| Area |
Current scope and handoff |
| National Highways |
Potholes only, on operational NH/NE carriageways mapped in the pinned 20 August 2026 OpenStreetMap extract. Matches open Rajmargyatra/1033; the maintainer is not guessed. |
| All 28 states + 8 Union Territories |
A confidently contained coordinate can use a conservative official state/UT grievance handoff. The complete GPS-accuracy circle must stay inside a checksum-pinned boundary; border ambiguity fails closed. |
| Exact city/authority routes |
Reviewed municipal, metropolitan, and authority-specific routes remain preferred wherever available. Nationwide fallback never replaces a more specific route. |
| 50 largest population centres |
All 50 from Census 2011 A-04(I). Existing reviewed/statewide routes stay preferred; 8 centres require both a conservative coordinate envelope and an exact structured city/state match before offering a neutral official grievance channel. Markers do not claim complete Urban Agglomeration boundaries. |
| Delhi |
Full Delhi NCT. Road damage uses PWD Sewa. NCR places outside NCT never inherit Delhi's route; Noida and Ghaziabad can qualify through the separate Uttar Pradesh route, while Faridabad retains its top-50 neutral route. |
National Highway routing runs first, followed by exact city/authority routes, then the
state/UT handoff. Boundaries suggest where to start a complaint; they do not prove who
owns or maintains a road. The user must review and complete every complaint in the
offered official app, portal, WhatsApp, dialler, share sheet, or email client. Nothing is
submitted automatically.
How it works
- Drive shows a live road view and counters while Maps or a call is open. At a typical 30 fps it samples about every fifth delivered camera frame, with a 166 ms timestamp fallback threshold, into durable three-view windows. It keeps only one raw burst waiting for live AI and retries unfinished saved windows after the drive.
- Dashcam mode keeps RTSP on the dashcam Wi-Fi while Maps, geocoding, and OpenAI remain
free to use the phone's default internet route. It uses phone GPS, disables audio,
saves selected complete frames, and never saves or uploads the whole dashcam stream.
- RTSP does not expose the dashcam sensor's true capture time. Until an exact camera/phone
pair is latency-calibrated, dashcam detections save evidence but deliberately omit
automatic authority/tender routing and repair verification; Phone camera keeps the
existing precise route. This prevents delayed video from being assigned to the next road.
- Every detection, saved-video replay, and repair view preserves the complete edge-to-edge
camera frame. The app may downscale or compress the whole image, but never crops, tiles,
masks, or substitutes a road region for model evidence.
- A selectable 15/30/60/90-minute active-time battery limit stops Drive automatically; paused time does not count. The default is 30 minutes.
- On a new install, Settings appears first so the API key and capture preferences are
configured before Drive and Photo are shown. Photo is one tap and pothole-only.
- OpenAI vision returns only Pothole: Yes/No, never a user-facing confidence score.
A Yes requires a localized cavity, an eroded edge or material-height transition,
visible surface loss, usable imagery, and consistent Drive views. Shallow concave
potholes remain eligible; flat patches, utility-cover repairs, gravel texture, ruts,
broad breakup, puddle ambiguity, construction beds, and speed breakers are No.
- Each decision records the surface type and strict defect type. Accepted potholes may
receive a small/medium/large app visual estimate; physical dimensions remain unknown
without a field measurement, and the estimate is labelled with its provenance and low
measurement confidence. It is not an official municipal size classification.
- Nearby repeat observations are grouped into one report; Debug mode retains each one.
- On a later live drive, Fixed requires a separate before/after AI check that clearly
sees the same footprint covered by completed, intact repair material. Probable,
obstructed, mismatched, or merely clean-looking views remain open for review.
- The app preserves the photo, coordinates, time, category, complaint draft, and official
reference ID locally. A genuinely temporary routing-data failure can be retried later;
permanent boundary/category refusals require a new report or added coverage.
- Pothole handoffs are enabled in all 28 states and 8 Union Territories, with a
road-specific channel where one exists.
- English, Kannada, Marathi, and Bengali are supported.
Complaint output
- BMC and the Bengaluru Central, East, North, South, and West city corporations have
authority-specific intake profiles. BDA is used only when separate evidence explicitly
identifies BDA responsibility; location inside Bengaluru is not enough.
- Complaint intake and road ownership are separate fields. A boundary can select where to
start a complaint without claiming that the same authority owns or maintains the road.
- Email, short WhatsApp, and copyable portal fields always retain coordinates, map link,
and routing. Portal fields are regenerated and copied immediately before the verified
official service opens; direct email includes a compressed full-frame evidence photo.
Karnataka, NHAI/MoRTH/NHIDCL, PMGSY, and State/UT procurement records may
produce a local research lead, but it is not included in complaint copy. Tender and
contractor details appear only when official evidence verifies the exact road segment,
carriageway scope, award, road owner, and active DLP/maintenance responsibility. If any
link is missing or ambiguous, both are omitted.
National Highway routing
- Runs before municipal routing anywhere in India.
- Uses 101 checksum-pinned tiles containing 680 NH/NE references from the pinned
20 August 2026 OpenStreetMap India extract.
- Refuses weak GPS, conflicting direction, nearby different highway references, missing
tiles, and altered data instead of guessing.
- Opens Rajmargyatra or 1033 and asks the official service to identify the maintaining
NHAI, NHIDCL, BRO, or State PWD unit.
Downloaded data packs
The APK contains the app and small manifests, not the large reference datasets. When
needed, it downloads a versioned state/UT pack or the relevant 2° National Highway tile
from this project's GitHub Pages site. The 101 highway geometry tiles total about 18 MB,
the 33 current National Highway research packs contain 1,859 records in 1,805,723 bytes,
the 36 PMGSY State/UT packs contain 17,717 records in 3,075,718 bytes, and the 34 official
State/UT notice packs contain 5,310 open notices in 4,225,170 bytes. Only the relevant files
are downloaded and cached. These remote packs do not enlarge the APK; the three manifests
add only about 100 KB to a future build. The Play closed-test binary already submitted to
Google remains unchanged. All inputs are filtered for explicit carriageway work, so
drain-, footpath-, sewer-, utility-, consultancy-, and roadside-plantation-only work is excluded even
when its title contains a road name.
Every downloaded pack is checked byte-for-byte against a checksum pinned in the app before
it is used, then cached locally. Missing, malformed, or altered required routing, contact,
or highway data makes authority routing fail closed—the app does not guess or reuse
unverified data.
If an optional contract or procurement pack is unavailable, the report continues without
a candidate. A verified cached pack is available after its first successful download,
although detection, geocoding, and relevant GIS checks still need their respective network
services. On a subsequent pack use, caches past their unused limits are pruned
automatically; Delete all app data removes the entire pack cache immediately.
A pack request contains no report, photo, or exact coordinates. GitHub Pages can receive
the device's IP address, connection metadata, and requested pack URL; the URL reveals the
selected state or an approximate 2° highway tile. See the
privacy policy.
Install
- Install the APK attached to the
latest release.
- On first launch, enter your OpenAI API key in Settings and choose Phone camera or
Dashcam. Phone mode needs camera access; both modes need precise location and notifications.
- Capture while safely stopped, or securely mount the phone before starting Drive.
- Review the image, location, authority, wording, and contract-verification status before
choosing an external complaint channel.
Important limits
- AI can miss damage or produce false positives. No field-validated accuracy percentage is
claimed.
- Dashcam mode requires a reachable H.264 RTSP-over-TCP stream. Vendor URLs, authentication, Wi-Fi
behaviour, decoder support, and camera-side delay vary; test the exact dashcam/phone pair
before relying on its GPS routing.
- Android may temporarily take the camera for a video call or another higher-priority app;
Drive pauses camera sampling and resumes automatically. Normal audio calls do not require
the camera. Device-specific battery managers can still stop long-running services.
- Selected pothole images and the user's API key go directly to OpenAI. Exact coordinates
go to OpenStreetMap Nominatim; Karnataka
locations query Karnataka GIS, and exact Hyderabad CURE checks query Telangana GIS.
State/UT containment is checked locally against downloaded, checksum-pinned ODbL
boundaries for all 28 states and 8 Union Territories.
The 8 structured-city routes require Nominatim's city/municipality and state fields;
a broad envelope or stale place label alone cannot select a route.
- Contract matching is optional and incomplete. The 26 August 2026 National Highway scan
read 3,258 MoRTH and 529 NHIDCL rows, normalized 1,950 current/open records
(1,939 + 11), and published the 1,859 with a mapped NH/NE reference. PMGSY retained
17,717 recent,
source-reported In Progress agreements from 211,007 rows; agreement details are
verified as source fields, but award, contractor, exact segment, and DLP are not.
The official State/UT notice catalog scanned 69,754 rows from 35 public feeds, rejected
64,444 through fail-closed scope/current-record checks, and retained 5,310 notices in 34
jurisdiction packs. It combines GePNIC with dedicated Bihar, Chhattisgarh, Gujarat,
Telangana, and Lakshadweep adapters. Andhra Pradesh remains blocked by undocumented
client-encrypted listing state; KPPP remains a separate Karnataka supplement.
- Research leads never prove that every tender or road is covered. Open notices are not
awards. Exact segment, scope, award, contractor, owner, warranty, and active DLP require
authoritative evidence; publication date proves none. The current public packs contain
no record satisfying that complete chain, so complaints currently name no contractor.
- National Highway coverage follows mapped NH/NE geometry, not the legal road register.
Parallel roads, junctions, weak GPS, missing tiles, and altered data fail closed.
- The project is not affiliated with or endorsed by a government body or data provider.
Read data sources and limits
for exact coverage, provenance, and known gaps.
Build and test
./tools/build-apk.sh
./tests/run-all.sh
# Explicit live-service checks: RUN_LIVE_TESTS=1 ./tests/run-all.sh
License
Code is MIT; data retains its source licences and terms. See LICENSE and
data sources and limits.
Pothole Reporter is an independent Android app that uses the phone camera or a connected dashcam to detect potholes while you drive, then helps you file a complaint through the correct official Indian government channel for that road. It never submits anything automatically; reports stay on the phone.