Skip to main content

​
Get Positions

Retrieve all available election positions (e.g., President, Governor, Senator, MP, MCA, Women Rep).

​
Response

​
positions
array
Array of position objects

​
Example

cURL
curl http://localhost:3000/positions
Response
[
  {
    "title": "President"
  },
  {
    "title": "Governor"
  },
  {
    "title": "Senator"
  },
  {
    "title": "Mp"
  },
  {
    "title": "Mca"
  },
  {
    "title": "WomenRep"
  }
]

​
Get Parties

Retrieve all registered political parties.

​
Response

​
parties
array
Array of party objects

​
Example

cURL
curl http://localhost:3000/parties
Response
[
  {
    "id": 1,
    "title": "Orange Democratic Movement",
    "logo": "/logos/odm.png"
  },
  {
    "id": 2,
    "title": "United Democratic Alliance",
    "logo": "/logos/uda.png"
  },
  {
    "id": 3,
    "title": "Jubilee Party",
    "logo": "/logos/jubilee.png"
  }
]

​
Get Candidates by Position and Area

Retrieve candidates for a specific position within a geographical area.

​
Path Parameters

​
position_type
string
required
The type of position. Accepted values:
  • President - National position
  • Governor - County-level position (area_id = county_code)
  • Senator - County-level position (area_id = county_code)
  • Mp - Constituency-level position (area_id = constituency_code)
  • WomenRep - Constituency-level position (area_id = constituency_code)
  • Mca - Ward-level position (area_id = ward_code)
​
area_id
integer
required
The geographical area identifier. The meaning depends on position_type:
  • For Governor/Senator: county_code
  • For Mp/WomenRep: constituency_code
  • For Mca: ward_code
  • For President: any value (ignored)

​
Response

​
candidates
array
Array of candidate objects

​
Examples

​
Get Presidential Candidates

cURL
curl http://localhost:3000/candidates/President/0

​
Get Governor Candidates for County 47

cURL
curl http://localhost:3000/candidates/Governor/47

​
Get MCA Candidates for Ward 1001

cURL
curl http://localhost:3000/candidates/Mca/1001
Response
[
  {
    "id": 42,
    "name": "John Doe",
    "gender": "Male",
    "photo": "/photos/candidate-42.jpg",
    "position_type": "Mca",
    "party_id": 1
  },
  {
    "id": 43,
    "name": "Jane Smith",
    "gender": "Female",
    "photo": "/photos/candidate-43.jpg",
    "position_type": "Mca",
    "party_id": 2
  }
]

​
Position Types

The Kenyan electoral system includes the following positions:

​
National Level

  • President - Head of state and government

​
County Level (47 counties)

  • Governor - County executive
  • Senator - County representative in the Senate

​
Constituency Level (290 constituencies)

  • Mp - Member of Parliament
  • WomenRep - Women’s Representative

​
Ward Level (1,450 wards)

  • Mca - Member of County Assembly

Build docs developers (and LLMs) love

Get started for freeTalk to us