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 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.

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", "score": 0.31 }
  ]
}

# 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 uses the AI summaries, so it finds meetings about a topic, not just ones that mention the word in passing. Raw full-agenda-text search is coming next.

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.