Start
The sandbox
Three fictional governments in the live shapes, free, for building before you go live.
A key that starts with htd_test_ reads the sandbox. It holds three fictional governments with every record family the live API sells, in the same shapes. Build against it, then swap in a live key.
The three towns
| Jurisdiction id | Name | Kind |
|---|---|---|
port-ellery | City of Port Ellery | A municipality inside Marlow County |
marlow-county | Marlow County | A regional district |
tolland-township | Tolland Township | A municipality inside Marlow County |
Nothing in the sandbox is a real place or person. Every link in it is under .example, a name reserved for examples, so a sandbox link never reaches a real site.
The sandbox holds only these three governments. Use their ids in jurisdiction, not the id of a real one.
How it behaves
- It is free. Sandbox requests show in the dashboard's usage but are never billed.
- It takes 10 requests a minute, per key. It is for building, not for load tests.
- It answers the same rows every time. The same request returns the same records, so your tests can rely on them.
- Its meetings fall between May and October 2026. Use dates in that span when you try
fromandto. - Every answer says
"environment": "sandbox". Check it in your code if you ever mix keys.
The sandbox has the same endpoints, the same parameters, the same errors and the same MCP tools as the live API.
Things to try
curl "https://data.heytownhall.com/v1/jurisdictions" \
-H "Authorization: Bearer $HTD_KEY"curl "https://data.heytownhall.com/v1/meetings?jurisdiction=port-ellery&from=2026-06-01&to=2026-08-31" \
-H "Authorization: Bearer $HTD_KEY"curl "https://data.heytownhall.com/v1/search?q=water%20main&jurisdiction=port-ellery" \
-H "Authorization: Bearer $HTD_KEY"Going live
Create a live key in the dashboard and swap it in. Nothing else in your code changes. Live answers carry real records, and their coverage is real coverage:
Coverage today is British Columbia. The United States is being added.