townhall.town API and developer docs
townhall.town has a small public API. It is free, needs no key or account, and returns the same sourced ballot data the site shows. The full description is the OpenAPI 3.1 spec. The current version is v1.
Endpoints
- GET /api/v1/agent?zip=78701 or POST /api/v1/agent with JSON {"zip":"78701"}: the ballot for a ZIP, streamed as newline-delimited JSON (application/x-ndjson). Send Accept: application/json to get only the final result as one JSON object.
- POST /api/v1/locate with JSON {"lat":30.2672,"lon":-97.7431}: the ZIP for a point, from the U.S. Census Geocoder. Coordinates go in the body, not the URL.
- /api/agent and /api/locate are unversioned aliases of the v1 endpoints, with identical behavior. They keep working; new code should use /api/v1.
- openapi.json: OpenAPI 3.1 description of every endpoint, with every parameter, response, header and error.
Get a ballot
Covered ZIPs: 78701 (Austin, Texas), 94103 (San Francisco, California), 10001 (New York, New York). Each line of the response is one JSON event. Step and status lines arrive while the data tools run. The last line has "type":"result" with the full ballot: districts, races, candidates, measures, live Polymarket prices and local Census data, each with its source. A 5-digit ZIP that is not covered ends with one "type":"unsupported" line instead.
curl -N "https://townhall.town/api/v1/agent?zip=78701"curl -N -X POST "https://townhall.town/api/v1/agent" -H "content-type: application/json" -d '{"zip":"94103"}'curl -s "https://townhall.town/api/v1/agent?zip=10001" -H "accept: application/json" | jq '.ballot.races[].title'Find a ZIP
Returns {"zip":"78701","source":"U.S. Census Geocoder (ZCTA)"}. Coordinates are not stored.
curl -X POST "https://townhall.town/api/v1/locate" -H "content-type: application/json" -d '{"lat":30.2672,"lon":-97.7431}'Errors
Every API error is JSON with Content-Type application/json and the shape {"error":{"code":"...","message":"..."}}. The zip must be exactly 5 digits; it is not trimmed or cut down.
- 400 invalid: a zip that is not exactly 5 digits, a body that is not JSON, or a missing or out of range lat or lon.
- 404 not_found: an unknown /api/ path, or a point with no ZIP.
- 405 method_not_allowed: a method the route does not support. The Allow header lists the supported ones.
- 429 rate_limited: too many requests. Wait the number of seconds in Retry-After.
- 500 internal: an unexpected server error.
- 502 upstream_unavailable: the Census Geocoder did not answer.
curl -i "https://townhall.town/api/v1/agent?zip=7870"{"error":{"code":"invalid","message":"zip must be exactly 5 digits, for example 78701."}}Research and interview
GET /api/research?zip=<ZIP>&race=<race id>&issues=<ids> streams newline-delimited JSON: candidate, step, citation, none and done events. A citation is the candidate's own words copied exactly from the page, with its URL: a sentence on their own campaign or official site (ownSite true), or words in quotation marks that another page attributes to them by name. 10 requests per minute per client.
POST /api/interview with JSON {"zip":"78701","messages":[{"text":"..."}]} returns {"answers":[{"issue","choice","words"}]}: Yes, Neutral or No only for questions the text clearly addresses, with the words that support each. Nothing typed is stored. 10 requests per minute per client.
Both carry the same RateLimit headers as /api/v1 and use the same JSON error model. Typed schemas: ResearchEvent, InterviewRequest and InterviewResult in /openapi.json.
curl -N "https://townhall.town/api/research?zip=94103&race=ca-gov&issues=housing"curl -s -X POST https://townhall.town/api/interview -H 'content-type: application/json' -d '{"zip":"78701","messages":[{"text":"Rent is too high"}]}'Rate limits
Limits are per client IP in a fixed 60-second window: 10 requests per minute on /api/v1/agent and 30 on /api/v1/locate (each alias shares its v1 counter). One ballot lookup on the site is one request. Counters live in memory on each server instance, so the limit is approximate, not a guarantee.
Every GET and POST response carries the IETF RateLimit-Policy and RateLimit headers (draft-ietf-httpapi-ratelimit-headers) and the common RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Over the limit, the API answers 429 with Retry-After in seconds and the usual JSON error body.
RateLimit-Policy: "agent";q=10;w=60
RateLimit: "agent";r=9;t=60
RateLimit-Limit: 10
RateLimit-Remaining: 9
RateLimit-Reset: 60429 Too Many Requests
Retry-After: 42
{"error":{"code":"rate_limited","message":"Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."}}Versioning and deprecation
The API is versioned in the URL path. The current version is v1 (/api/v1/...), and every response carries an API-Version: 1 header. Adding endpoints or optional fields is not a breaking change and ships in place.
Breaking changes ship under a new path (/api/v2/...). The old version keeps working for at least 90 days after the new one launches. During that time its responses carry a Deprecation header (RFC 9745), a Sunset header (RFC 8594) with the shutdown date, and a Link to this policy. The unversioned /api/agent and /api/locate aliases follow the same policy.
Example client
A tiny Node 18+ script with no dependencies, scripts/townhall-ballot.mjs in the source code. It is an example to copy, not an official or published package.
node scripts/townhall-ballot.mjs 78701 # final result as JSON
node scripts/townhall-ballot.mjs 94103 --stream # every event as it arrivesUse and limits
The data is nonpartisan and sourced, and the AI summary only restates the returned records. Please cache results on your side and keep request rates modest. Market prices are market prices, not forecasts. Confirm dates and polling places with your state or county election office.