How it works

Real civic data, a shelter conceit, and one rule above all: the city’s record decides every pet’s fate. Code maps 311 records to outcomes. A model may only restyle a bio built from those records, and only people approve merges and adoption notes.

Where the pets come from

Every pet is a complaint from NYC 311 Service Requests from 2020 to Present (NYC Open Data, dataset erm2-nwe9) with complaint type “Street Condition” and descriptor “Pothole”, in Queens Community Board 13. The shelter holds every such complaint filed in the last 180 days, plus every one still open, however old. Nothing is sampled. The sync fetches only records changed since the last run, and saves every raw page it receives with its retrieval time and SHA-256 checksum.

Outcomes

• In the shelter: Open for less than 60 days.
• Feral: Still open after 60 days.
• Adopted into forever pavement: Closed: the city repaired it.
• Ghost: Closed: no defect was found.
• Transferred: Referred elsewhere or closed as a duplicate.
• Unmapped: Closed with a resolution no mapping covers yet.
• Lost stray: any of the above, but with no coordinates in the record. Listed by street, not on a map.

Open complaints are in the shelter until they have been open 60 days, then they go feral. Closed complaints get their outcome from resolution mappings: documents a person wrote, one per exact phrase the city uses. Phrases nobody has mapped go to a public Unmapped bucket instead of being guessed.

The schema

• complaint311: the city record exactly as published, never edited, rewritten only when its content hash changes.
• pothole: the pet. Name, temperament, bio, rounded location and outcome are all derived; the outcome is written only by the sync. Its status history is an append-only list inside the pet, and every entry cites the complaint field that changed.
• resolutionMapping, clusterDecision, adoption, syncRun: the decisions people make, and the sync’s own log.

Raw records and pet fields are kept apart so the city’s data is never mixed with ours. You can check any pet against the 311 record it came from.

Workflows

Three processes are defined with the Sanity Workflows engine (0.36.0, early access): the pothole lifecycle (Reported → In the shelter → Adopted, Ghost, Transferred, Feral or Unmapped), cluster review (Proposed → Approved or Rejected) and adoption moderation (Submitted → Approved or Rejected). All three pass the engine’s validation and its test bench.

Status: all three definitions are deployed to the dataset (version 1, 4 October 2026). Their documents use dotted IDs, which Sanity never serves to anonymous readers, so public pages need a read-only server proxy to show workflow state (being built). The sync applies the lifecycle rules in code and is the only writer of outcomes; only a robot token may fire the lifecycle’s “record outcome” action, and only a person may approve a merge or an adoption note. Engine gates are advisory by design, so server checks do the real enforcement.

Data terms

The City of New York does not vouch for the accuracy or completeness of data provided by this site, or for the usefulness or integrity of the site. This site uses data that has been modified for use from its original source, NYC.gov, the official website of the City of New York.

Locations are rounded to about 100 m and house numbers are never shown. Everyone who reports a pothole and everyone who fixes one is doing the city a favour; the jokes here are about the potholes.