Results
Use Case
The /results endpoint is designed to be used together with four other APIs, not in isolation. Each of those APIs returns a summary list of contests; /results gives you the complete details for a single contest:
- Seats: returns a list (with summary details) of every contest held for a particular constituency; use
/resultsto get the complete details for a specific contest. - Candidates: returns a list (with summary details) of every contest a candidate has stood in; use
/resultsto get the complete details for a specific contest. - Elections: returns (among other things) a list of every seat contested in a general election; use
/resultsto get the complete details for a selected seat. - By-Elections: returns a list of all by-elections ever held; use
/resultsto get the complete details for any one of them.
In short, you should use this endpoint to allow users to zoom into a specific contest, similar to what is done on our Seats, Candidates, Elections, and By-Elections dashboards.
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 params
The /results endpoint mandates three parameters, all of which come directly from the response of the four companion APIs listed above. In each case, the mandatory parameters you need (seat, state, and date) are already present in the objects returned by those APIs. Pass them straight through—no transformation needed.
https://api.electiondata.my/v1/results| Parameter | Type | Required | Description |
|---|---|---|---|
seat | string | Yes | Constituency identifier, e.g. 'P.001 Padang Besar' or 'N.01 Banggi'. Taken directly from the seat field in the companion API response. |
state | string | Yes | State name, e.g. 'Perlis' or 'Sabah'. Taken directly from the state field in the companion API response. |
date | string | Yes | Polling day in ISO 8601 format (YYYY-MM-DD), e.g. '2022-11-19'. Taken directly from the date field in the companion API response. |
All three parameters are mandatory. Missing any one will return a 400 Bad Request error. A date that is not in YYYY-MM-DD format will also return 400. A valid combination that does not correspond to a real contest will return 404 Not Found.
Step 2: Get Result
Pass the seat, state, and date you obtained from a companion API to retrieve the full contest result.
A successful 200 OK response returns a JSON object with two keys: ballot and stats.
ballot: an array of every candidate who stood in the contest, ordered by votes received (descending):
| Field | Type | Description |
|---|---|---|
name | string | Candidate's full name. |
party_uid | string | Unique party identifier (e.g. '004-PAS'). |
party | string | Acronym of the candidate's party (e.g. 'PAS'). |
coalition_uid | integer | Numeric coalition identifier (0 if the party contested independently). |
coalition | string | Coalition name (e.g. 'PN'). 'ALONE' if the party contested independently. |
votes | integer | Total votes received (zero for uncontested wins). |
votes_perc | float | Share of valid votes as a percentage (null if uncontested). |
result | string | One of: 'won', 'won_uncontested', 'lost', or 'lost_deposit'. |
stats: an array containing a single object with aggregate statistics for the contest:
| Field | Type | Description |
|---|---|---|
date | date | Polling day in ISO 8601 format (YYYY-MM-DD). |
voters_total | integer | Total number of registered voters for this contest. |
voter_turnout | integer | Total number of votes cast, including rejected votes (zero if uncontested). |
voter_turnout_perc | float | Turnout as a percentage of registered voters (null if uncontested). |
votes_rejected | integer | Number of votes rejected during counting. |
votes_rejected_perc | float | Rejected votes as a percentage of total ballots cast (null if uncontested). |
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 (null if uncontested). |
Try It Out
Pick a sample contest below to populate the fields, then fire a live request.