By-Elections
Use Case
Use this endpoint to build a by-elections browser, similar to the one on our By-Elections dashboard. A user opens the page and sees a list of every Pilihan Raya Kecil (PRK) ever held in Malaysia—the seat, the date, who won, and by how much. If you pair it with the /results endpoint, they can also drill into the complete details for any individual contest.
Just follow the 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 PRKs
https://api.electiondata.my/v1/byelectionsThis endpoint takes no parameters and returns every by-election from the first in 1957 till the present day. The list is only updated when a new by-election is called, 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 object with a single data key containing an array of every by-election, ordered from the most recent to oldest. Each object in the array contains:
| Field | Type | Description |
|---|---|---|
seat | string | Constituency identifier (e.g. 'P.011 Sungei Perak Ulu'). |
state | string | State name (e.g. 'Perak'). |
date | date | Polling day in ISO 8601 format (YYYY-MM-DD). |
name | string | Winner's full name. |
party_uid | string | Unique party identifier (e.g. '001-UMNO'). |
party | string | Acronym of the winning party (e.g. 'UMNO'). |
coalition_uid | integer | Numeric coalition identifier (0 if the party contested independently). |
coalition | string | Coalition name (e.g. 'PERIKATAN'). 'ALONE' if the party contested independently. |
voters_total | integer | Total number of registered voters for this contest. |
voter_turnout | integer | Total votes cast, including rejected votes. |
voter_turnout_perc | float | Turnout as a percentage of registered voters. |
votes_rejected | integer | Number of votes rejected during counting. |
votes_rejected_perc | float | Rejected votes as a percentage of total ballots cast. |
majority | integer | Winning margin, i.e. winner's votes minus runner-up's votes. |
majority_perc | float | Majority as a percentage of total valid votes. |
Try It Out
Fire a live request to examine the response containing the full list of by-elections.