Voting methods API

Tallies ranked ballots under plurality, Borda, Condorcet and instant-runoff (IRV), returning each method's winner, full round-by-round IRV, pairwise Condorcet check and Borda scores. Answers 'Who wins under each voting method?', 'Is there a Condorcet winner or a cycle?'.

Price$0.1per request

MethodPOST

Route/v1/gametheory/voting-result

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

social-choicevotingcondorcetbordainstant-runoffirvpluralityranked-choice

API URLhttps://x402.hexl.dev/v1/gametheory/voting-result

Integration docs

Example request

{
  "candidates": [
    "A",
    "B",
    "C"
  ],
  "ballots": [
    {
      "ranking": [
        "A",
        "B",
        "C"
      ],
      "count": 4
    },
    {
      "ranking": [
        "B",
        "C",
        "A"
      ],
      "count": 3
    },
    {
      "ranking": [
        "C",
        "B",
        "A"
      ],
      "count": 2
    }
  ],
  "method": "condorcet"
}

Example response

{
  "method": "condorcet",
  "totalVotes": 9,
  "winner": "B",
  "firstPreferences": {
    "A": 4,
    "B": 3,
    "C": 2
  },
  "bordaScores": {
    "A": 8,
    "B": 12,
    "C": 7
  },
  "pluralityWinner": "A",
  "bordaWinner": "B",
  "condorcetWinner": "B",
  "irvWinner": "B",
  "irvRounds": [
    {
      "tallies": {
        "A": 4,
        "B": 3,
        "C": 2
      },
      "eliminated": "C"
    },
    {
      "tallies": {
        "A": 4,
        "B": 5
      }
    }
  ],
  "condorcetExists": true,
  "interpretation": "Under condorcet, the winner is B."
}

Input schema

{
  "type": "object",
  "required": [
    "candidates",
    "ballots"
  ],
  "properties": {
    "candidates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "examples": [
        [
          "A",
          "B",
          "C"
        ]
      ]
    },
    "ballots": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "examples": [
        [
          {
            "ranking": [
              "A",
              "B",
              "C"
            ],
            "count": 4
          },
          {
            "ranking": [
              "B",
              "C",
              "A"
            ],
            "count": 3
          },
          {
            "ranking": [
              "C",
              "B",
              "A"
            ],
            "count": 2
          }
        ]
      ]
    },
    "method": {
      "type": "string",
      "enum": [
        "plurality",
        "borda",
        "condorcet",
        "irv"
      ],
      "examples": [
        "condorcet"
      ]
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}