Parties

Use Case

Use these endpoints to build a party or coalition performance tracker, similar to the one on our Parties dashboard. A user selects a party or coalition, a state, and an election type, and gets back a time-series of every election they contested in that scope—how many seats they contested, how many they won, and their vote share.

The endpoint covers all parties and coalitions that have ever contested an election, including historical variants that have since been renamed or merged. Just follow the 2 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 parties

To let users search for a party or coalition, first fetch the full list of every entity that has ever contested an election, along with its canonical UID.

GEThttps://api.electiondata.my/v1/parties/dropdown

This endpoint takes no parameters. The list is only updated when a new election is held, 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 an object with a data array. Each entry contains:

Field	Type	Description
`type`	string	'party' or 'coalition'.
`uid`	string	The historical UID this entry represents. May be a legacy variant—use maps_to to resolve to the canonical current form.
`maps_to`	string	The canonical current UID. If uid === maps_to, this entry is already the current form.
`acronym`	string	Short name as used at the time (e.g. 'AMANAH').
`name_en`	string	Full English name (e.g. 'National Trust Party').
`name_bm`	string	Full Bahasa Malaysia name (e.g. 'Parti Amanah Negara').

Always query Step 2 using maps_to, not uid. The dropdown includes historical variants so users can search by any name a party has ever used—but each variant’s results are stored under the canonical current UID. For example, 001-PERIKATAN maps to 001-BN: a user who searches for “PERIKATAN” should get the full consolidated PERIKATAN + BN history. 001-BN maps to itself, so it works either way. The rule is simple: take whatever the user picks, read its maps_to, and pass that as the uid parameter.

Step 2: Get party results

Pass the maps_to value (and its type) from the dropdown, along with a state and election type, to retrieve the time-series of results for that entity.

GEThttps://api.electiondata.my/v1/parties/results

Parameter	Type	Required	Description
`type`	string	Yes	Entity type from the dropdown—'party' or 'coalition'.
`uid`	string	Yes	Unique identifier from the dropdown (e.g. '046-AMANAH').
`state`	string	Yes	One of 18 valid values: Malaysia, Semenanjung, Johor, Kedah, Kelantan, Melaka, Negeri Sembilan, Pahang, Perak, Perlis, Pulau Pinang, Sabah, Sarawak, Selangor, Terengganu, W.P. Kuala Lumpur, W.P. Labuan, W.P. Putrajaya.
`election_type`	string	Yes	'parlimen' for parliamentary elections or 'dun' for state assembly elections. Note: dun is not valid for Malaysia, Semenanjung, or any W.P.

All four parameters are required; omitting any returns 400 Bad Request. The API validates type, state, and election_type strictly and returns a descriptive 400 for unrecognised values. If the entity never contested in the requested state and election type, the response is {"results": []}—this is not an error.

A successful 200 OK response returns an object with a results array ordered from most recent to oldest. Each object contains:

Field	Type	Description
`party_type`	string	'party' or 'coalition'—mirrors the type request parameter.
`state`	string	Mirrors the state request parameter.
`type`	string	'parlimen' or 'dun'—mirrors the election_type request parameter.
`known_as_uid`	string	The UID the entity used at the time of this election. May differ from the requested uid if the party has since been renamed or merged.
`known_as`	string	The acronym the entity used at the time of this election.
`coalition`	string	The coalition the party contested under at the time, if any (e.g. 'PH'). Omitted for coalition rows.
`coalition_uid`	string	Unique coalition identifier, if any (e.g. '007-PH'). Omitted for coalition rows.
`election_name`	string	Human-readable election name—'GE-NN' for general elections, 'SE-NN' for state elections.
`date`	date	Polling day in ISO 8601 format (YYYY-MM-DD).
`seats_contested`	integer	Number of seats contested in the specified state for this election.
`seats_won`	integer	Number of seats won.
`seats_total`	integer	Total seats available in that state for this election.
`seats_contested_perc`	float	seats_contested / seats_total × 100.
`seats_won_perc`	float	seats_won / seats_total × 100.
`votes`	integer	Raw vote count across all contested seats in that state.
`votes_perc`	float	Share of total valid votes cast in that state for this election.

Semantic errors

Beyond missing or unrecognised parameters, the API enforces two additional rules for election_type=dun:

state=Malaysia or state=Semenanjung returns 400—DUN results cannot be aggregated to national or regional level.
Any state=W.P. * returns 400—federal territories have no state assembly.

Try It Out

Load the party list, pick an entity, choose a state and election type, and fire a live request.

Previous ← Candidates Next Elections →