# Jurisdictional

> Jurisdictional is an open data platform building the open record of who governs every U.S. address.
> It maps every jurisdiction, agency, governing body, position, and public official — from federal to local — and makes this data freely available as structured JSON.

The core concept is **Juricode**: given any U.S. address or coordinates, Juricode identifies every layer of government that governs that location — federal, state, congressional district, county, city, school district, and more.
Each jurisdiction has geographic boundaries (PostGIS/TIGER), and a Juricode query finds every jurisdiction whose boundary contains a point (a precomputed grid first, then PostGIS `ST_Contains` on the simplified boundary).
Each jurisdiction carries its Census `geoid` and, where Open Civic Data defines one, its `ocd_id` (OCD division id).

Key entities in the data model:
- **Jurisdictions** — Geographic boundaries with levels: federal, state, county, municipal, special district
- **Agencies** — An agency is a department, a division or a dependent agency of a government; the government is the jurisdiction. `classification` is `department` (directly under the government), `division` (under another agency, `parent_id`) or `dependent_agency` (own charter or board, counted inside its government by the Census); `agency_type` is its function, separately
- **Bodies** — Legislative bodies, councils, commissions, and governing boards
- **Positions** — Elected offices, appointments, and government roles
- **People** — Public officials and elected representatives holding positions (deduplicated across bodies via tenures)
- **Services** — Permits, licenses, benefits, and public services offered by agencies
- **Domains** — .gov domain registrations linked to jurisdictions and agencies (sourced from CISA dotgov registry)

Data sources include the Census TIGER/Line boundary files, the CISA .gov registry, data.gov datasets, and community contributions.
All gathered data is published as structured JSON in a public GitHub repository.

## API

- [Juricode by Address](https://jurisdictional.org/api/v1/juricode?address=300+Hemlock+St+Vacaville+CA): Geocode an address and return all governing jurisdictions
- [Juricode by Coordinates](https://jurisdictional.org/api/v1/juricode?lat=38.35&lng=-121.97): Skip geocoding, go straight to spatial lookup (faster, more reliable)
- Every juricode layer carries `display_name` (e.g. `City of Vacaville`, `Solano County`; null for a county, place or county subdivision whose Census LSAD is not on file), `code`, a short badge (`US`, `CA`, `CD4`, `SD3`, `AD11`, `SOL`, `D4`, `VAC`, `VUSD`; null when a district name has no number), and `seats_total` / `seats_filled`, the seats that represent the point on that layer and how many have a holder on file
- [Juricode with seats](https://jurisdictional.org/api/v1/juricode?lat=38.35&lng=-121.97&include=seats): Pass **`include=seats`** (address or lat/lng, combinable with `statistical`) to add each layer's `seats`: `[{id, label, body: {id, name}, holder}]`. A district's seat sits on the district's layer even when its body belongs to the parent (Assembly District 11 → `Assembly Member, District 11` on the State Assembly; a supervisorial district → its supervisor). A layer's own seats that no district elects (a mayor, at-large council seats) sit on that layer; seats for districts elsewhere are left out. `holder` is `{id, full_name, identifiers, image, image_url, image_source, image_license, term_start, term_end, source_url, verified_on}` or null for an open seat, where `image` is the portrait object `{url, sizes: {"64", "128", "256"}, full, jpeg: {"128", "full"}, width, height, license, attribution, photographer_credit, source_page_url, placeholder}` (WebP URLs; `jpeg` holds the JPEG fallbacks; `source_page_url` is the page the photo was published on), non-null only for an approved portrait whose license may be shown (`public-domain-us-gov`, `public-domain-ca-gov`, `public-domain-fl-gov`, `government-published-headshot`); `identifiers` is as in Person detail; `term_start` and `term_end` are dates from a source, null when none was published; `source_url` and `verified_on` are the page that last showed the holder in the seat and the date it did, null when none is on file
- [Juricode with statistical areas](https://jurisdictional.org/api/v1/juricode?lat=38.35&lng=-121.97&include=statistical): By default juricode returns the governing stack and hides county subdivisions that govern nothing (Census county divisions in CA, WA, TX and ~17 other states; Census FUNCSTAT other than `A`). Pass **`include=statistical`** (address or lat/lng) to get them too. Every `county_subdivision` layer carries `census_funcstat`, `census_lsad`, a derived `kind` (`governing`, `non_governing`, or `unclassified` while FUNCSTAT is not yet loaded) and `kind_label` (e.g. `Town`, `Township`, `Charter Township`, `Census County Division`; `County Subdivision` for an unmapped LSAD). Any `include` value other than `statistical` or `seats` is a 400
- [Juricode shape previews](https://jurisdictional.org/api/v1/juricode?lat=38.35&lng=-121.97&geometry=preview): Pass **`geometry=preview`** (address or lat/lng) to draw the stack as shapes, about 0.3–1 KB per layer. Each layer gets `preview: {svg_path, point, viewbox, aspect}`: `svg_path` is an SVG path `d` string with integer coordinates, the layer's outer rings fitted and centred in `viewbox` `0 0 100 100` (y down); `point` is the queried location as `[x, y]` in that box; `aspect` is the shape's width over height. The federal layer is the contiguous US only
- [Juricode with GeoJSON](https://jurisdictional.org/api/v1/juricode?lat=38.35&lng=-121.97&include_geometry=true): Pass **`include_geometry=true`** (address or lat/lng) for each layer's simplified boundary as `geojson`. A full stack is hundreds of KB (the federal layer alone is ~590 KB); add `geometry=full` for full resolution
- [Jurisdictions List](https://jurisdictional.org/api/v1/jurisdictions?query=Vacaville&level=place): Browse/search jurisdictions. Param is **`query`** (not `q`; `q` is accepted as an alias). Optional `level`, `state`, `page`, `per_page`; exact lookups `ocd_id` (Open Civic Data division id, e.g. `ocd-division/country:us/state:ca/place:vacaville`) and `jid` (`level:geoid`)
- [Jurisdiction Autocomplete](https://jurisdictional.org/api/v1/jurisdictions/autocomplete?query=Vacaville&state=CA): City/place picker. Param is **`query`** (`q` alias accepted); optional `state` (two-letter abbreviation, any case) restricts results to that state, and `limit` (default 10, max 20)
- [Jurisdiction Detail](https://jurisdictional.org/api/v1/jurisdictions/:id): Get a single jurisdiction (population, links, its display name and Census codes, its counties, its .gov domains, whether it is a government: see the entries below). Its boundary comes only with `include_geometry=true`, as `geojson`; related records via comma-separated `include`: `agencies`, `parent`, `children`, `officials`, `services`, `coverage`, `organization`
- [Jurisdiction names and Census codes](https://jurisdictional.org/api/v1/jurisdictions/70118): `display_name` is the name a resident says ("City of Vacaville" for the Census name "Vacaville"), the same as the juricode layer's; null when no Census LSAD is on file or the LSAD is not one we name. `census_lsad` is the Census legal/statistical area code (e.g. `25` city, `43` town, `06` county). `census_function_code` is a special district's Census of Governments function code (e.g. `24`) and `census_function` its label (`Local Fire Protection`); null when none is on file
- [Jurisdiction government flag](https://jurisdictional.org/api/v1/jurisdictions/70118): `government` is `true`, `false` or null (undecided), and `government_reason` says why, by the 2022 Census of Governments rules behind `get_government_count`. True: `in_census_of_governments_2022` (also `incorporated_place_counted_as_municipal` for a county subdivision that is a city, `district_of_columbia`, `territory`). False: e.g. `census_designated_place`, `statistical_or_inactive`, `no_township_governments_in_state`, `no_county_government`, `dependent_school_systems_only`, `inactive`, `electoral_district`. Null: e.g. `active_but_not_in_census_2022`, `not_in_census_2022`, `dependence_unknown` (school districts), `no_classfp`, `outside_census_scope`, `not_a_census_of_governments_type` (tribal areas)
- [Jurisdiction counties](https://jurisdictional.org/api/v1/jurisdictions/70118): `counties` lists the counties a place or county subdivision lies in, largest share first: `[{id, name, geoid, share}]`, where `share` is the fraction of its area in that county (a place can cross county lines; overlaps under 0.0001 are boundary slivers and left out). `[]` when no boundary is on file; null for other levels. A place's `parent_id` stays null: containment is by boundary
- [Jurisdiction .gov domains](https://jurisdictional.org/api/v1/jurisdictions/70118): `domains` lists the .gov domains from the CISA dotgov registry that this jurisdiction registered, by name: `[{domain_name, domain_type, organization_name, suborganization_name, jurisdiction_match, jurisdiction_matched_at}]`. `jurisdiction_match` is the rule that linked the domain (e.g. `place_name`, `county_name`); null when it was linked some other way. `[]` when none is linked
- [Jurisdiction government id](https://jurisdictional.org/api/v1/jurisdictions/70118): `ocd_jurisdiction_id` is the government's Open Civic Data Jurisdiction id, derived from its division id: `ocd-jurisdiction/country:us/state:ca/place:vacaville/government`. Null unless `government` is true and `ocd_id` is set. The jurisdiction row is the government; there is no separate government record
- [Jurisdiction organization](https://jurisdictional.org/api/v1/jurisdictions/70118?include=organization): **`include=organization`** adds the government's org chart: `organization: {government: {name, ocd_jurisdiction_id}, departments, dependent_agencies, unclassified, bodies}`. Each department is agency JSON (as in Agencies List) with `children`, its divisions, nested the same way; `unclassified` holds agencies not yet given a classification; each body is `{id, name, legislative_type, staffed_by}`. `include=agencies` stays a flat list
- [Jurisdiction coverage](https://jurisdictional.org/api/v1/jurisdictions/70118?include=coverage): **`include=coverage`** adds `coverage: {score, present, expected, percentage}`, how complete our data on it is (boundary, links, agencies, bodies, officials and the like); `score` is 0–1 and `percentage` its rounded percent
- [Jurisdiction children](https://jurisdictional.org/api/v1/jurisdictions/:id?include=children): **`include=children`** adds `children`, every jurisdiction spatially inside this one at the next modelled levels, sorted by name and uncapped: a state's counties; a county's places and school districts; the federal layer's states; `[]` for a place. Each child is a summary `{id, name, level, state_abbr, geoid, ocd_id, parent_id, population, center}`; containment is by boundary, so a child's `parent_id` is often null. With `include_geometry=true` each child also gets `geojson`
- [Jurisdiction officials](https://jurisdictional.org/api/v1/jurisdictions/:id?include=officials): **`include=officials`** adds `officials`: `[{position, body, current_holder}]` for every filled seat on the jurisdiction's bodies and its agencies' bodies. `position` is `{id, label, role, electing_jurisdiction_id}`; `electing_jurisdiction_id` is the district that elects the seat (null when at-large). `current_holder` is `{id, first_name, last_name, image, image_url, image_source, image_license, portrait, political_affiliation}`; `image` and `image_url` are the same legacy portrait URL, and a null `image_license` means it is not cleared for display. `portrait` is the portrait object `{url, sizes: {"64", "128", "256"}, full, jpeg: {"128", "full"}, width, height, license, attribution, photographer_credit, source_page_url, placeholder}` (WebP URLs; `jpeg` holds the JPEG fallbacks; `source_page_url` is the page the photo was published on), non-null only for an approved portrait whose license may be shown (`public-domain-us-gov`, `public-domain-ca-gov`, `public-domain-fl-gov`, `government-published-headshot`); it is named `portrait` here because `image` is already the URL string
- [Jurisdiction services](https://jurisdictional.org/api/v1/jurisdictions/:id?include=services): **`include=services`** adds `services`, the services of the jurisdiction's own agencies, sorted by name: `[{id, name, service_type, description, online_url, eligibility_requirements, cost, agency: {id, name}}]` (the same shape as Nearby Search)
- [Jurisdiction pages](https://jurisdictional.org/api/v1/jurisdictions/70118): `pages` lists the government's website pages by what they are for: `[{id, kind, url}]`, in kind order, `[]` when none. `kind` is one of `meetings`, `agendas`, `minutes`, `budget`, `financial_report`, `municipal_code`, `open_data`, `data_json`, `about`, `open`, `foia`, `privacy`, `accessibility`, `vulnerability_disclosure`, `no_fear_act`, `inspector_general`, `digital_strategy` (the list grows). `open_data` is a data portal people browse; `data_json` is the machine-readable DCAT-US catalog at /data.json; `financial_report` covers ACFRs, CAFRs and audits. A page serving two kinds appears once per kind. Agency Detail and Jurisdiction Bodies carry `pages` for the agency or body. `budget_url` is kept: the url of the oldest `budget` page, or null
- [Jurisdiction Bodies](https://jurisdictional.org/api/v1/jurisdictions/70118/bodies): Governing bodies for a jurisdiction. Each has `staffed_by`: the agency that staffs it (agency JSON as in Agencies List), or `[]`, and `pages`, its website pages (as on Jurisdiction Detail)
- [Agencies List](https://jurisdictional.org/api/v1/agencies?jurisdiction_id=70118): List agencies for a jurisdiction. Text search with **`query`** (`q` alias accepted), e.g. `?query=vacaville police`: every word must match the agency's name, description, phone, email or its jurisdiction's name; combinable with `jurisdiction_id`, `limit` (max 500) and `offset`. `logo_url` comes with `logo_source` (the page it came from) and `logo_license`; a null license means the logo is not cleared for display. Every agency carries `classification`, `parent_id` and `parent: {id, name, classification}` (null for a department). Filter with **`classification=`** (comma list of `department`, `division`, `dependent_agency`) and **`parent_id=`** (the agencies directly under that agency); without them every classification is returned
- [Agency Detail](https://jurisdictional.org/api/v1/agencies/:id?include=bodies,services,children): Get a single agency with related bodies and services. `ancestors` lists the agencies above it, top-level first (`[{id, name, classification}]`, for a breadcrumb); **`include=children`** adds `children`, the agencies directly under it. A dissolved or merged agency's id answers **410 Gone** with `merged_into: {type, id, url}`, `type` being `jurisdiction` (dissolved into its government) or `agency` (merged)
- [Services List](https://jurisdictional.org/api/v1/services?jurisdiction_id=70118): What a government offers residents, sorted by name. Filter with `jurisdiction_id` (its own agencies' services), `agency_id`, **`service_type=`** (comma list of `health`, `education`, `housing`, `transportation`, `employment`, `business`, `public_safety`, `utilities`, `recreation`, `social_services`: what it is for), **`action=`** (comma list of `apply`, `pay`, `report`, `reserve`, `register`, `renew`, `request`, `look_up`, `subscribe`, `schedule`: what a resident does; any of them matches) and `query` (`q` alias); `limit` (max 500) and `offset`. An unknown `service_type` or `action` is a 400 naming it and the valid values. Each service is `{id, name, description, service_type, actions, eligibility_requirements, application_process, required_documents, cost, processing_time, contact_info, online_url, capacity_upper_bound, people_served, services_provided, agency: {id, name}, jurisdiction: {id, name, level}, inserted_at, updated_at}`; `cost` is a decimal string or null. Not an HSDS or Open311 document
- [Service Detail](https://jurisdictional.org/api/v1/services/:id): One service, `{data: <service>}` in the Services List shape; an unknown id is a 404
- [Meetings for a body](https://jurisdictional.org/api/v1/bodies/3/meetings?include=agenda_items&limit=50): `include=agenda_items`, `upcoming`, `limit` (max 200), `since`/`until` (YYYY-MM-DD), `order=asc|desc` (default newest-first unless upcoming)
- [Meetings for a jurisdiction](https://jurisdictional.org/api/v1/jurisdictions/70118/meetings?limit=50): Same list params as body meetings
- [Meetings for an agency](https://jurisdictional.org/api/v1/agencies/:id/meetings): Meetings across that agency's bodies
- [Meeting detail](https://jurisdictional.org/api/v1/meetings/:id?include=agenda_items): Single meeting
- [Positions for a body](https://jurisdictional.org/api/v1/bodies/3/positions): Body has many positions; each may have a `current_tenure` with a `person` (vacant = `current_tenure: null`). `current_tenure.start_date` and `end_date` are dates and agree with juricode seats' `term_start` and `term_end`: `start_date` is null when no source gave one, and `end_date` is the recorded departure, else the scheduled term end. `current_tenure.source_url` and `verified_on` are the page that last showed the holder in the seat and the date it did (null when none is on file). `person` carries `image` plus `image_url`, `image_source` and `image_license`, and `portrait`: the portrait object as in Person detail's `image` (named `portrait` because `image` is the URL string here)
- [Person detail](https://jurisdictional.org/api/v1/people/:id): One official, including current positions. `image` is the portrait object `{url, sizes: {"64", "128", "256"}, full, jpeg: {"128", "full"}, width, height, license, attribution, photographer_credit, source_page_url, placeholder}` (WebP URLs; `jpeg` holds the JPEG fallbacks; `source_page_url` is the page the photo was published on), non-null only for an approved portrait whose license may be shown (`public-domain-us-gov`, `public-domain-ca-gov`, `public-domain-fl-gov`, `government-published-headshot`). The legacy `image_url` comes with `image_source` (the page it came from) and `image_license`; a null license means it is not cleared for display. `identifiers` is the Popolo list `[{scheme, identifier}]` of the external ids on file, sorted by scheme: `bioguide` (S001150), `openstates` (ocd-person/<uuid>), `wikidata` (Q65074410); `[]` when none. `updated_at` is when the record last changed (ISO 8601, UTC). Each of `current_positions` carries `source_url` and `verified_on` as on juricode seat holders
- [Nearby Search](https://jurisdictional.org/api/v1/nearby?lat=38.35&lng=-121.97&radius=5000): Find agencies and services within a radius. Each service is `{id, name, service_type, description, online_url, eligibility_requirements, cost, agency: {id, name}}`
- [At Point](https://jurisdictional.org/api/v1/jurisdictions/at_point?lat=38.35&lng=-121.97): Find jurisdictions containing a lat/lng point
- [My feed](https://jurisdictional.org/api/v1/me/feed?limit=25): **Requires `Authorization: Bearer <token>`**; personal only, there is no anonymous feed. What changed in the record, and which meetings were recorded, for what the signed-in person follows (`/follow`) and for their saved addresses' stacks matched against their enabled topics; newest first. `{items, next_before}`; pass `next_before` back as `before=` for the next page; `limit` 1–100. Item: `{id, kind, occurred_at, subject: {type, id, name}, fields, jurisdiction: {id, name, level, geoid, ocd_id}, topics, why, source}`; `kind` is `meeting_scheduled`, `tenure_started`, `entity_added` or `entity_updated`; `why` lists every match, `{follow: {id, type, followable_id}}` or `{address: {id, label}, topics}`
- [MCP Tools](https://jurisdictional.org/api/mcp/tools): Model Context Protocol endpoint for AI tool use
- [OAuth Discovery](https://jurisdictional.org/.well-known/oauth-authorization-server): RFC 8414 metadata: authorization, token, registration and device authorization endpoints
- [MCP Protected Resource Metadata](https://jurisdictional.org/.well-known/oauth-protected-resource/api/mcp/message): RFC 9728 metadata for the MCP endpoint, naming https://jurisdictional.org as its authorization server

## MCP (Model Context Protocol)

Jurisdictional exposes an MCP server at `https://jurisdictional.org/api/mcp/message` (JSON-RPC 2.0, Streamable HTTP).
Protocol versions `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`: `initialize` echoes a supported `protocolVersion`, else answers `2025-11-25`; later messages may send it in `MCP-Protocol-Version` (absent means `2025-03-26`).

**Read tools** — no auth required:
- `set_location` — set user location by address or lat/lng, returns juricode (jurisdiction stack)
- `explore` — search civic data with jurisdiction scoping and topic filtering
- `search_jurisdictions`, `get_jurisdiction`, `find_jurisdictions_at_point` — jurisdiction queries
- `search_agencies`, `get_agency`, `find_agencies` — agency queries; `search_agencies` matches every word of `query` against the agency's name, description, phone, email or its jurisdiction's name, so `Vacaville Police` finds Vacaville's `Police Department`
- `search_services`, `get_service`, `find_services` — service queries
- `search_places` — parks, libraries, schools and community centers by name, jurisdiction and type
- `search_people`, `get_person` — public officials
- `search_bodies`, `get_body` — governing bodies

**Write tools** — require sign-in (see "Signing in" below):
- `propose_change` — propose a field update to a jurisdiction, agency, body, service, position, person or page (`url` or `kind`). Fails, listing the valid fields, if the entity or field does not exist
- `create_entity` — create a new agency, body, service, position, person, place, meeting, or agenda_item. Bodies take `url` (the body's own page) and `meeting_url` (where its agendas and minutes are published). A person with `position_id` is seated in that position (with `source_url`); an explicit `position_id: null` is an error and creates no one, so leave it out for a person without a seat. To seat a person already on file (found with `search_people`), pass `person_id` with `position_id` and `source_url` and no name fields: it writes only the tenure and returns `person_id`, `tenure_id` and `person_existed: true`, and it is an error if the person is missing or already holds a current tenure on that seat. Places (parks, libraries, schools, community centers) require `place_type` + `source_url` and take an address, `phone` and coordinates; meetings require `body_id` + `start_time`; agenda items require `meeting_id`. A page (`entity_type: "page"`) is a website page by what it is for: `kind`, `url`, `source_url` and `jurisdiction_id`, plus `agency_id` or `body_id` (one, in that jurisdiction) when the agency or body owns it; no name. One page serving meetings and agendas is two calls; a repeat returns `duplicate: true`; an unknown `kind` is an error listing the kinds. `get_jurisdiction_details`, `get_agency_details` and `get_body_details` return `pages`
- `import_jurisdiction` — create a jurisdiction's agencies, their bodies and services, and its council in one all-or-nothing call; nest children instead of passing parent ids, get back a ref→id map; retries match existing names instead of duplicating; `dry_run: true` to check first; an item cites its `source_url`, and a field read on another page cites that page with `field_sources: {"description": "<that page>"}`
- `import_civicplus_directory` — deterministic import of a CivicPlus `/directory.aspx` page (verbatim department names, council as a jurisdiction-level body); dry run by default, diffs against what exists. Send the page with `priv/scripts/civicplus_import.mjs`, not through a model
- `get_change_status` — check status of proposed changes
- `submit_sourcing_result` — submit results for a sourcing task
- `research_entity` — research missing fields for an entity via LLM-powered web scraping
- `gather` — fetch a government web page via headless Chrome (returns HTML + screenshot). Allowed domains: .gov, .mil, granicus.com, legistar.com, wikipedia.org

**Admin tools** — listed and callable only with an admin token:
- `list_pending_changes` — the `propose_change` rows awaiting review, oldest first, optionally narrowed by `jurisdiction_id`, `entity_type` or `entity_id`: each change's id, entity, field, old and new value, `source_url`, source key and tier, submitter and created time
- `review_change` — `change_id`, `decision: approve | reject`, `reason` (required to reject). Approve publishes the value to the entity, as /admin/contributions does

Signing in: the server follows the MCP authorization spec (2025-11-25). In Claude Code, run `/mcp`, choose `jurisdictional` and Authenticate (or `claude mcp login jurisdictional`), then approve on jurisdictional.org; Claude Code stores and refreshes the token.
Read tools never answer 401. A write, image or admin tool called without a token, or any request with an invalid token, is HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="https://jurisdictional.org/.well-known/oauth-protected-resource/api/mcp/message"`.
Other MCP clients: discover via that metadata and `/.well-known/oauth-authorization-server`; register with `POST /oauth/register` (RFC 7591; public clients, `token_endpoint_auth_method: none`; redirect URIs `https` or `http` on localhost/127.0.0.1/[::1], loopback on any port); authorize with PKCE S256 and `resource` (RFC 8707, this server or its MCP endpoint, else `invalid_target`); refresh with `grant_type=refresh_token`, `refresh_token`, `client_id` at `POST /api/v1/auth/token` (rotated on each use). No scopes.
Without browser sign-in: log in at https://jurisdictional.org and visit /auth/cli or Settings → API Tokens for a token.
A device without a browser signs in with the OAuth 2.0 device grant (RFC 8628): `POST /api/v1/auth/device` with `client_id=jurisdictional-cli` returns `{device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval}`; the person approves the code at https://jurisdictional.org/device; poll `POST /api/v1/auth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `device_code` and `client_id` every `interval` seconds until it returns `{access_token, refresh_token, expires_in, token_type}` or an RFC 6749 error (`authorization_pending`, `slow_down`, `access_denied`, `expired_token`, `invalid_grant`).
A native app signs in through the system browser with the authorization code grant and PKCE (RFC 6749 §4.1, RFC 7636, RFC 8252): open `https://jurisdictional.org/oauth/authorize?response_type=code&client_id=civic-bot&redirect_uri=...&code_challenge=...&code_challenge_method=S256&state=...` (S256 required; redirect URIs registered per client and matched exactly); the person approves and the browser returns to `redirect_uri?code=...&state=...&iss=https://jurisdictional.org`; then `POST /api/v1/auth/token` with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id` and `code_verifier` returns the same token body. Codes last 120 seconds and work once.
Set `JURISDICTIONAL_TOKEN` in your environment, then pass it as `Authorization: Bearer $JURISDICTIONAL_TOKEN`.

Rate limits (per UTC day; every response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset`):
- No token: 100 requests per IP.
- Free token: 2,000 reads. Write tool calls are not counted.
- Past the limit: HTTP 429; on MCP a JSON-RPC error with code `-32000` and `data: {reason: "rate_limited", limit, reset_at}` plus `signup_url` (no token) or `upgrade_url` (token).

Example (propose a change):
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "propose_change",
    "arguments": {
      "entity_type": "agency",
      "entity_id": 12345,
      "field_name": "website_url",
      "new_value": "https://example.gov",
      "source_url": "https://example.gov/about"
    }
  }
}
```

## Skill

The [jurisdictional-skill](https://github.com/jurisdictional/jurisdictional-skill) is a Claude Code plugin for civic data gathering: the gather skill plus this MCP server.
Install, inside Claude Code: `/plugin marketplace add jurisdictional/jurisdictional-skill`, then `/plugin install jurisdictional@jurisdictional`.
MCP server only: `claude mcp add --transport http jurisdictional https://jurisdictional.org/api/mcp/message`
Usage: `/gather 300 Hemlock St, Vacaville, CA`
Flow: set location → explore gaps → research government websites → propose changes

## CLI

[jurisdictional-cli](https://github.com/jurisdictional/jurisdictional-cli) is the command-line client for this API.
Install: `curl -fsSL https://github.com/jurisdictional/jurisdictional-cli/releases/latest/download/install.sh | sh`
Builds: Linux x86_64 and arm64 (glibc 2.35+, OpenSSL 3), Apple silicon Macs; other systems build from source.
Usage: `jurisdictional juricode "Vacaville, CA"`, `jurisdictional agencies list --jurisdiction 70118`, `jurisdictional tool NAME --param value`, `jurisdictional api METHOD PATH`
Sign in: `jurisdictional login` (browser approval at https://jurisdictional.org/device; no password)
Save responses: `--save DIR` writes each body plus `DIR/index.json`
Page: https://jurisdictional.org/cli

## Pages

- [Developers](https://jurisdictional.org/developers): API quickstart — run juricode on any address, endpoints, MCP setup, project ideas, honest coverage numbers
- [CLI](https://jurisdictional.org/cli): The jurisdictional command-line client — install, sign in, examples, GitHub Actions
- [Juricode Demo](https://jurisdictional.org/juricode): Interactive 3D visualization — enter an address, see stacked jurisdiction layers
- [Map](https://jurisdictional.org/map): Full-screen map of U.S. with state boundaries and juricode search
- [Jurisdictions](https://jurisdictional.org/jurisdictions): Browse all jurisdictions
- [Agencies](https://jurisdictional.org/agencies): Browse government agencies
- [Bodies](https://jurisdictional.org/bodies): Browse governing bodies
- [Positions](https://jurisdictional.org/positions): Browse government positions
- [People](https://jurisdictional.org/people): Browse public officials (with provenance and change history)
- [Services](https://jurisdictional.org/services): Browse public services
- [Spatial Search](https://jurisdictional.org/search): Location-based search for agencies and services
- [Research](https://jurisdictional.org/research): Published studies of how U.S. government is organized, each with its method, as-of date and data
- [Official government sites in Common Crawl](https://jurisdictional.org/research/official-sites-in-common-crawl): How many of 35,447 official domains below the federal level have pages in two recent Common Crawl crawls, by cause; counts only ([CSV](https://jurisdictional.org/research/crawl-coverage-by-type-2026-11-06.csv))

## Data

- [Jurisdictional Data Repo](https://github.com/jurisdictional/data): Structured JSON files for all jurisdictions, agencies, and officials
- [Source Code](https://github.com/jurisdictional/jurisdictional): Phoenix/Elixir application source
- [Skill Source](https://github.com/jurisdictional/jurisdictional-skill): Claude Code skill for civic data gathering

## License

- [Data license](https://jurisdictional.org/license): The database is open under the ODbL 1.0 (https://opendatacommons.org/licenses/odbl/1-0/), and each record's contents under the DbCL 1.0. Use it for anything, commercial included, with credit and share-alike. Credit: "Contains information from Jurisdictional (https://jurisdictional.org), made available under the ODbL 1.0." A paid commercial license waives share-alike and attribution for closed products; newsrooms, nonprofits and governments can apply for one at no cost. Portraits and logos carry their own per-image license, and facts from upstream sources keep their own terms.
- Public record pages and public API reads carry `link: <https://opendatacommons.org/licenses/odbl/1-0/>; rel="license"`.
- Contributions (propose_change, create_entity, import_jurisdiction, /contribute) are published under the same ODbL 1.0 and DbCL 1.0.

## Ecosystem

- **jurisdictional.org** — data platform, API, rules engine
- **civic.bot** — conversational widget for exploring civic data (embeddable)
- **gather.jurisdictional.org** — headless browser service for fetching .gov pages
- **jurisdictional-data** — structured JSON data repository on GitHub
- **jurisdictional-skill** — Claude Code skill for data gathering and contribution
- **ogenda** — open agenda management platform (boards, meetings, minutes, video)