← POLIAPI/MOCKUPS//V1 ENDPOINTS
api · mockup
// /v1 endpoints

Fourteen endpoints.
Everything civic.

REST is the lowest-common-denominator integration. Every backend, no-code tool, and junior developer can hit this surface in five minutes. Below is the full canonical /v1 contract.

// full surface

Every endpoint, with method, rate limit, and intent.

Method
Path
Intent
Rate
GET
/v1/ballot?address=...
Single-call address → full ballot (the killer endpoint).
60 rpm
GET
/v1/jurisdictions
Search 19k+ cities, counties, districts.
120 rpm
GET
/v1/jurisdictions/{ocd_id}
Resolve by Open Civic Data ID.
240 rpm
GET
/v1/elections
Upcoming + historical, filterable by jurisdiction/date.
120 rpm
GET
/v1/ballots/{id}
Measures, races, candidates for one election.
120 rpm
GET
/v1/candidates/{id}
Bio, finance, endorsements, stances.
240 rpm
GET
/v1/measures/{id}
Plain-language summary + full text + fiscal note.
240 rpm
GET
/v1/officeholders?ocd_id=...
Current seats, terms, contact info.
120 rpm
GET
/v1/results/{election_id}
Precinct-level returns as reported.
60 rpm
GET
/v1/finance/{candidate_id}
FEC + normalized state filings.
120 rpm
GET
/v1/polling-places?address=...
Day-of, early vote, drop boxes.
60 rpm
GET
/v1/districts/{ocd_id}.geojson
District geometries for mapping.
60 rpm
GET
/v1/changes?since=...
Versioned diff feed for any object.
30 rpm
POST
/v1/webhooks
Subscribe to ballot / candidate / measure events.
10 rpm
// sample response

GET /v1/ballot?address=…

The single response shape every other endpoint is derived from. Stable, OCD-keyed, versioned.

200 OK · application/json
{
  "address": "200 College St, Asheville, NC 28801",
  "ocd_id": "ocd-division/country:us/state:nc/place:asheville",
  "districts": [
    { "type": "cd",      "ocd_id": "ocd-division/country:us/state:nc/cd:11" },
    { "type": "council", "ocd_id": "ocd-division/country:us/state:nc/place:asheville/council_district:3" }
  ],
  "upcoming_elections": [
    {
      "id": "elec_nc_2026_05_05_prim",
      "date": "2026-05-05",
      "races": [{ "office": "City Council, D3", "candidates": [...] }],
      "measures": [{ "id": "msr_nc_ash_housing", "title": "Affordable Housing Bond" }]
    }
  ],
  "provenance": {
    "scraped_at": "2026-02-14T08:22Z",
    "confidence": 0.94,
    "corroborated_by": ["ncsbe.gov", "buncombecounty.gov"]
  }
}
// auth, errors, pagination

The boring contract details that close enterprise deals.

Auth
Bearer tokens (Authorization header). Publishable + secret key pairs. Per-key rate limits and scopes.
Errors
RFC 7807 problem+json. Stable error codes. machine_message + human_message on every error.
Pagination
Cursor-based (?cursor=…&limit=…). Max 200/page. Total counts via separate /count endpoints.
Versioning
URL-versioned (/v1, /v2). Minor changes additive only. Deprecation headers 12 months before removal.
Caching
ETag + Last-Modified. CDN-cacheable for public data. Stale-while-revalidate hints in headers.
SDKs
Official JS/TS, Python, Ruby, Go. Auto-generated from OpenAPI 3.1 spec. SDK changelog matches API changelog.