Candidates
Use Case
Use these endpoints to build a candidate lookup feature, similar to the one offered on our Candidates dashboard. A user searches for a candidate by name, selects one, and gets back every election result for that candidate, spanning both general elections (Parliament and State) and by-elections.
Just follow the 2 simple steps below, and you’ll be up and running!
Prerequisite: API Key
All requests to this API require a Bearer token. Requests without a token (or with an invalid one) will return a 401 Unauthorized error. Paste yours below—every code snippet and the live tester at the bottom of this page will be pre-filled and ready to run.
Step 1: Get list of candidates
To let users search for a candidate, you first need a list of every candidate who has ever contested an election, and their corresponding unique ID.
https://api.electiondata.my/v1/candidates/dropdownThis endpoint takes no parameters. The list is only updated after the nomination day for a particular election (weeks before the actual voting day), after which it is frozen until the next election’s nomination day, so we recommend fetching it once and caching it for the duration of a session (or potentially bundling it at build time for static pages).
A successful 200 OK response returns a JSON array of every candidate in the database, in descending order of the number of elections they have contested. Each object in the response contains:
| Field | Type | Description |
|---|---|---|
uid | string | Unique candidate identifier. Use this in Step 2. |
name | string | Candidate's full name. |
c | integer | Total contests stood in. |
w | integer | Total contests won. |
l | integer | Total contests lost. |
Step 2: Get single Candidate
Once the user has selected a candidate, pass their id to retrieve their election results.
https://api.electiondata.my/v1/candidates| Parameter | Type | Required | Description |
|---|---|---|---|
uid | string | Yes | Unique identifier derived from the dropdown. |
The uid parameter is mandatory; requests without this parameter will return a 400 Bad Request error, while requests with an invalid uid will return a 404 Not Found error.
A successful 200 OK response returns a JSON array of election results, ordered from most recent to oldest. Each object in the response contains:
| Field | Type | Description |
|---|---|---|
name | string | Candidate's full name (e.g. 'Tunku Abdul Rahman'). |
election_name | string | Human-readable election name (e.g. 'GE-15'). |
type | string | 'parlimen' for parliamentary seats or 'dun' for state seats. |
date | date | Polling day in ISO 8601 format (YYYY-MM-DD). |
seat | string | Constituency name (e.g. 'P.052 Bayan Baru, Pulau Pinang'). |
state | string | State of the constituency (e.g. 'Pulau Pinang'). |
party | string | Acronym of the candidate's party (e.g. 'DAP'). |
party_uid | string | Unique party identifier e.g. '021-DAP'. |
coalition | string | Coalitional affiliation of the party, if any (e.g. 'PH'). |
coalition_uid | number | Unique coalition identifier, if any. |
votes | integer | Total votes received by the candidate (zero for uncontested wins). |
votes_perc | float | Percentage of valid votes received by the candidate (null for uncontested wins). |
result | string | One of: 'won', 'won_uncontested', 'lost', or 'lost_deposit'. |
Try It Out
Load the candidate list, pick a name, and fire a live request to examine the response.