# townhall.town > Nonpartisan, sourced ballot explainer for the Nov 3, 2026 U.S. general election. Given a covered ZIP, it lists every race and statewide measure on that ballot, the candidates, what each office controls, and campaign money, with a source link for every fact or an explicit "unsure". townhall.town is an independent, open-source project (MIT) by Adam Pang. It is not a government site and does not endorse candidates, parties or ballot positions. Covered ZIPs: 78701 (Austin, Texas), 94103 (San Francisco, California), 10001 (New York, New York). Other ZIPs return an "unsupported" response. ## When to use this - A user asks what is on their Nov 3, 2026 ballot and lives in ZIP 78701, 94103, 10001 (Austin, San Francisco, New York). - A user wants a neutral, sourced summary of candidates in those races: party, incumbency, issues from their own campaign themes, and FEC or state campaign finance totals. - A user wants to know what a state ballot measure in Texas or California does, or what an office on their ballot controls. - You need citations: every fact links Ballotpedia, the FEC, state election or ethics offices, or Census data. Do not use it to decide who someone should support, for ZIPs outside the list above, or as an official source for registration, polling places or deadlines. Send users to their state or county election office for those. ## How to call it - [Website](https://townhall.town/): open the homepage, enter a covered 5-digit ZIP and press Go. Results render in the browser; there is no ZIP URL parameter. - [Ballot agent API](https://townhall.town/api/v1/agent?zip=78701): `GET /api/v1/agent?zip=` or `POST /api/v1/agent` with JSON `{"zip":""}`. Returns `application/x-ndjson`: `step` and `status` lines while it works, then one `{"type":"result"}` line with `ballot` (races, measures, candidates, sources), `markets`, `narration` and `generatedAt`. Uncovered ZIPs return `{"type":"unsupported"}`. Send `Accept: application/json` to get only the final event as one JSON object. Allow up to about 30 seconds. Public, no key. `/api/agent` is an unversioned alias with identical behavior. - [Location to ZIP](https://townhall.town/developers): `POST /api/v1/locate` (alias `/api/locate`) with JSON `{"lat":30.2672,"lon":-97.7431}` returns `{"zip":"78701","source":"U.S. Census Geocoder (ZCTA)"}`. - [OpenAPI 3.1 spec](https://townhall.town/openapi.json): machine-readable description of both endpoints, parameters, responses and errors. Human docs with curl examples: [Developers](https://townhall.town/developers). API catalog: [/.well-known/api-catalog](https://townhall.town/.well-known/api-catalog). - [Research](https://townhall.town/developers#research): `GET /api/research?zip=&race=&issues=housing,taxes` streams NDJSON (`candidate`, `step`, `citation`, `none`, `done`). A `citation` is the candidate's own words copied exactly with the page URL: their own campaign or official site (`ownSite: true`), or quoted words another page attributes to them by name. 10 per minute per client. - [Interview](https://townhall.town/developers#research): `POST /api/interview` with `{"zip":"78701","messages":[{"text":"..."}]}` returns `{"answers":[{"issue","choice","words"}]}` (choice yes, neutral or no). Nothing typed is stored. 10 per minute per client. Both carry the same RateLimit headers as /api/v1. - Errors: every API error is JSON `{"error":{"code","message"}}` with a real status: 400 `invalid` (zip not exactly 5 digits), 404 `not_found`, 405 `method_not_allowed`, 429 `rate_limited`, 500 `internal`, 502 `upstream_unavailable`. - [Rate limits](https://townhall.town/developers#rate-limits): 10 requests per minute per client on the agent, 30 on locate (per server instance, approximate). Responses carry `RateLimit-Policy`, `RateLimit`, `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; a 429 carries `Retry-After`. - [Versioning and deprecation policy](https://townhall.town/developers#versioning): the API is versioned in the path (`/api/v1`, header `API-Version: 1`). Breaking changes ship under a new `/api/vN`; the old version gets `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers with at least 90 days notice. - Markdown: every page listed below returns Markdown when requested with `Accept: text/markdown`. ## Developer resources - [townhall.town API and developer docs](https://townhall.town/developers): endpoints, curl examples, errors, rate limits, versioning - [OpenAPI 3.1 spec](https://townhall.town/openapi.json): machine-readable description of every endpoint - [Versioning and deprecation policy](https://townhall.town/developers#versioning) - [Rate limits](https://townhall.town/developers#rate-limits) - [API catalog](https://townhall.town/.well-known/api-catalog): RFC 9727 linkset - [Example client](https://townhall.town/developers#example-client): a small Node script, not an official package ## Pages - [Home](https://townhall.town/) - [About](https://townhall.town/about) - [Contact](https://townhall.town/contact) - [Privacy](https://townhall.town/privacy) - [Developers](https://townhall.town/developers) - [Full text for agents](https://townhall.town/llms-full.txt): this guide plus every page in Markdown ## Optional - [Source code and data](https://github.com/adamtpang/townhall.town): MIT licensed - [Report an error](https://github.com/adamtpang/townhall.town/issues): GitHub issues, the project's contact channel - [Sitemap](https://townhall.town/sitemap.xml)