# jp-elections

> Which local and national elections are scheduled in a Japanese prefecture, and when? Notice dates, voting days, term expiry dates and seats as published by prefectural election commissions, with the official page URL first in every answer. Hosted MCP and HTTP: no install. English labels (translated by this service), local government codes, source and freshness receipt per item, and a change history kept since October 2026. 15 of 47 prefectures read so far; the rest are listed with their official pages. Free. Election-level facts only: no candidate data, no vote counts.

Data source: the published election schedule and term expiry pages of Japanese prefectural election commissions (one or more HTML pages per covered prefecture; URLs in every answer). Facts are relayed with attribution; original tables are not redistributed. English labels are translated by MK Career Planning; municipality English names follow the Japan Meteorological Agency area names. Not an official service of any election commission or of the Government of Japan.
Election-level schedule facts only (election name, type, notice date, voting day, term expiry date and number of seats as published), relayed from the election schedule pages of Japanese prefectural election commissions. This service does not handle candidates, parties, vote counts or election bulletins, and does not assess or forecast outcomes. The official election commission page is authoritative. Not an official service of any election commission or of the Government of Japan.
Statuses (elections_upcoming): found (complete=false if some pages could not be used), none_in_checked_pages (only when every page for the prefectures asked about was read and parsed within 72 hours; not a statement that no election will be held), not_covered (prefecture not read yet; its official page is listed), unknown (a page is not loaded, gone or unreadable, and nothing was found), stale (a page was last read more than 72 hours ago, and nothing was found).
Changes (election_changes): a voting day that moves on the page is recorded as modified with the previous and new date (date_changes), not as a removal plus an addition. A page that disappears is page_gone and its elections become unknown; it is not read as a cancellation.
Not handled: candidates, parties, vote counts, turnout, results, election bulletins, voting places and early-voting hours.
Each schedule page is read about once a day. History (election_changes) starts at tracking_since and is dated by when this service observed a change.
Free history window: change history recorded by this service is served for the last 30 days. A since earlier than that returns the last 30 days with history_window.clamped true (requested_since, served_since); older history can be requested as a paid product (not yet offered). tracking_since still shows when recording started.

## Connect

- MCP (streamable HTTP): https://jp-elections-production.mk-career-planning.workers.dev/mcp
- OpenAPI: https://jp-elections-production.mk-career-planning.workers.dev/openapi.json
- x402 discovery: https://jp-elections-production.mk-career-planning.workers.dev/.well-known/x402

## Quickstart

- Developer quickstart (MCP client configs, free curl/TypeScript calls, how to read official_check, status and coverage, attribution): https://jp-elections-production.mk-career-planning.workers.dev/quickstart

## Free tools

- catalog: List the tools of this server with prices, data sources, licensing, daily limits and data freshness.
- elections_upcoming: Which elections are scheduled in a Japanese prefecture between two dates? Name (Japanese and an English label we translate), type, local government code, notice date, voting day, term expiry and seats as published, with the official election commission page URL and a source receipt (URL, fetched_at, sha256, page update text). Prefectures not covered yet are listed with their official pages. Election-level facts only: no candidate data, no vote counts. Check the official page first.
- election_changes: What changed on Japanese prefectural election schedule pages since a date? From this service's own daily reads: elections added, modified (with before/after dates and the changed fields), removed from the page, and pages that disappeared, became unreadable or came back. History starts at tracking_since. Free window: last 30 days (an earlier since is clamped; see history_window). Election-level facts only. Check the official page before relying on a date.
- get_receipt: Re-fetch the stored result of a settled paid call by its receipt_id, for when the response was lost after payment. Free. Unknown or unsettled receipt ids return RECEIPT_NOT_FOUND. Results are kept for 90 days after settlement.
- HTTP: GET https://jp-elections-production.mk-career-planning.workers.dev/v1/elections/upcoming, GET https://jp-elections-production.mk-career-planning.workers.dev/v1/elections/changes return the same data as the MCP tools. GET https://jp-elections-production.mk-career-planning.workers.dev/v1/receipts/<receipt_id> is get_receipt.

## Payments

This server offers free tools only. It does not request or accept x402 payments.

## Rate limits

- Free calls (free HTTP endpoints under /v1/ and free MCP tools) are limited to 300 requests per 60 seconds per client (a client is keyed by a one-way hash of its IP address and the first 64 characters of its User-Agent; neither is stored. The User-Agent can be set by anyone, so this split is for fairness between clients behind a shared gateway, not a security control). Over the limit, HTTP returns 429 RATE_LIMITED with a Retry-After header and MCP tools return the error RATE_LIMITED. Paid calls are not rate limited.

## Provenance and fetch_status

Responses carry provenance[] (source, upstream_updated_at, retrieved_at, content_sha256, parser_version, fetch_status). fetch_status values:

- found: The upstream document was retrieved and contains the data used for this answer.
- empty: The upstream was retrieved, but it has no item for this query (for example JMA had no bulletin for that area in its feeds, or the municipality is not in the list). The state is unknown: empty does NOT mean 'none in effect'.
- stale: The data was retrieved but is older than the freshness threshold for its kind; treat it with care.
- unavailable: The upstream could not be retrieved, read or used (network error, withdrawn bulletin, paused source, or data not yet loaded).
- unsupported: The query is outside what this source covers (for example a date JMA does not issue warnings for yet, or a period before the source's records).

## Errors

- RECEIPT_NOT_FOUND (get_receipt)
- RATE_LIMITED (free calls over the per-client limit; HTTP 429 with Retry-After; not charged)

## Terms

- Fresh: the page was read successfully within 72 hours. Elections from stale, missing or unreadable pages are not returned; those pages are listed in coverage.unavailable_pages.
- Keep the attribution (source and 'processed by MK Career Planning') and the official page URL when you pass results on.

## Privacy and support

- Operator: MK Career Planning
- Terms of Service: https://jp-elections-production.mk-career-planning.workers.dev/terms
- Privacy policy: https://jp-elections-production.mk-career-planning.workers.dev/privacy
- Support (free): https://jp-elections-production.mk-career-planning.workers.dev/support (mk.career.planning@gmail.com)