Skip to main content
The World Republic API returns the party registry, test elections and their results, and counts of verified citizens and parties, as JSON. It only reads, and any website may call it.
  • Base URL: https://www.worldrepublic.org/api/v1
  • Authentication: none; there is no key and no sign-in.
  • OpenAPI document: openapi.json describes every endpoint and field, and the endpoint pages are generated from it.

Endpoints

Every endpoint is a GET.
  • Pages hold 100 parties. Pass the nextOffset of one page as the offset of the next; it is null on the last page.
  • search matches names, descriptions and leader usernames. The first page of a search also carries total.
  • sort orders the list: newest (the default), votes (drawn in closed test elections) or subsidies (allocated). A ranked list carries each party’s totalVotes or subsidiesAllocated. A ranking can’t be combined with search, and its offset is at most 20,000.
  • includeUnlisted=true adds the parties the default list leaves out: those still awaiting moderation review and those flagged as spam. Each party’s moderation field says which.
  • /elections takes status and limit. status is open, upcoming or closed; limit keeps the first 1 to 100 in the list’s order, so ?status=closed&limit=1 is the latest result. total counts every election that matches, before the limit.
  • Search is limited per IP address, per minute. Over the limit, a search answers 503 with a Retry-After header.

Errors

An error answers with a status code and a body like this:

Data conventions

  • Timestamps are ISO 8601, in UTC. Ids are UUIDs.
  • Per-party results appear only once an election has closed. While it is open, the only vote figure is ballotsCast, the total number of ballots.
  • Every election is marked binding: false. Test elections are experimental and non-binding, and confer no public office, mandate or authority.
  • A party whose content was withheld keeps its votes in results, but its partyId is null.
  • Party names and descriptions are written by party leaders, not by us.
  • Responses are not cached. The API reads exactly what the app shows, so a party removed from the app disappears from the API at the same time.
  • Subsidies are WDD allocations, each released over 365 days. An election not yet distributed shows null, never a zero.