API & search reference

Everything here is free, keyless, CORS-open, and CC BY 4.0 — every record links back to its official source. Four ways in, deepest first: a nationwide search API, the per-city JSON, the bulk dataset, and an MCP server for AI agents.

Search API · Per-city JSON · Bulk dataset · MCP (AI agents) · embed widget

1. Nationwide full-text search

Ask “which places, anywhere, discussed X?” across every city, county, and school board we cover, at once — ranked, with a snippet and a direct link. Searches the plain-English briefs and extracted decisions (what each meeting was actually about). Rebuilt continuously. A zero-result search means nobody in our corpus said it, which is not the same as nobody saying it — see coverage.

GET https://search.theboringparts.com/search?q=YOUR+QUERY

Parameters

q — your query. Supports quoted "exact phrases", OR, and -exclusion like a search box (e.g. q="short-term rental" -hotel).
limit — results to return, 1–50 (default 25).
state — optional, full state name (e.g. state=Texas).
kind — optional, city or school (school boards).

▶ Try it: “data center”

# every jurisdiction discussing data centers, ranked
curl -s "https://search.theboringparts.com/search?q=data+center&limit=10"

# school boards on a specific topic
curl -s "https://search.theboringparts.com/search?q=book+ban&kind=school&state=Florida"

Response

{
  "query": "data center", "count": 10,
  "results": [
    { "city": "Washington", "state": "New Jersey", "kind": "city",
      "body": "Green Team", "date": "2026-05-14",
      "headline": "Green Team to discuss data center ordinance",
      "snippet": "...proposed data center ordinance and grid impact...",
      "url": "https://mytown.theboringparts.com/city/washington-nj/#m1234",
      "agenda_url": "https://washingtonboro-nj.org/agenda/2026-05-14.pdf",
      "minutes_url": null,
      "source": "https://washingtonboro-nj.org/agenda/2026-05-14.pdf",
      "score": 0.31 }
  ]
}

source is the jurisdiction’s own document — the agenda if we have it, else the minutes, else its portal page. Cite that, not us. Matched words in snippet are wrapped in <b>; everything else in it is plain text from the source document, so escape it before rendering.

# Python
import requests
r = requests.get("https://search.theboringparts.com/search",
                 params={"q": '"police budget"', "limit": 25}).json()
for x in r["results"]:
    print(f'{x["city"]}, {x["state"]} — {x["headline"]}  {x["url"]}')

Ranking prefers the AI summaries, so it surfaces meetings about a topic above ones that mention the word in passing — but the raw agenda and minutes text is searched too, which is how a bill number buried on page 40 of a packet still turns up. Broad one-word queries scan millions of documents and can exceed our 100-second request budget; a quoted phrase or a state filter returns in seconds. Prefer a widget to code? embed this search.

2. Per-city JSON

Everything known about one place. meetings.json is the meeting list; city.json is the superset with every context layer attached. Rebuilt hourly, CORS-open.

GET https://mytown.theboringparts.com/city/CITY-SLUG/meetings.json   # meetings only
GET https://mytown.theboringparts.com/city/CITY-SLUG/city.json       # + all layers below

The slug is the last part of a city's page URL (/city/chicago/). Enumerate every slug via /municipalities.json. city.json includes any of these blocks that exist for that place (empty ones are omitted):

member_votes — named roll-call votes (who voted how) on divided motions
officials — the governing-body roster · election_results — candidate vote totals + winners
matters — per-agenda-item planning/zoning/development records
gov_finances — municipal budget (revenue/spending/debt) · building_permits — housing units permitted
ballot_measures — direct-democracy propositions (pass/fail + tally)
demographics, home_value_trend, federal_awards, campaign_finance, permits (licenses)

▶ Try it: Chicago — a large real payload. Full column-level schema on the schema page.

3. Bulk dataset (everything, one download)

The whole corpus across the whole country — 28 tables as SQLite + Parquet, on HuggingFace. This is the option for real analysis (joins across votes, decisions, budgets, elections).

# pandas — read any table directly from the Hub
import pandas as pd
votes = pd.read_parquet("hf://datasets/jazzypajamas/mytown-local-gov-meetings/data/member_votes.parquet")

# or the full SQLite
# curl -L -o mytown.db.gz https://archive.theboringparts.com/data/mytown.db.gz ; gunzip mytown.db.gz

Key join keys: muni_id → municipalities.id, meeting_id → meetings.id. See the dataset page for the table list, citation, and license.

4. MCP server (for AI agents)

Point an LLM at the whole dataset. The MyTown MCP server is on PyPI — tools include search_meetings (the nationwide search above), get_city_context, filter_dataset, and list_cities.

pip install mytown-mcp
# then add to your MCP client config, e.g. Claude Desktop:
{ "mcpServers": { "mytown": { "command": "mytown-mcp" } } }

Source + tool docs: github.com/mrjakob07/mytown-mcp. Once connected, ask your assistant things like “which school boards in Texas voted on book policies this year?” and it queries this data live.

License & attribution

CC BY 4.0 — use it for anything, credit “MyTown / theboringparts.com” with a link. Summaries are AI-generated from official documents; verify against the linked primary source before relying on a specific detail. Citation block on the dataset page.