Open Election API

https://electiondata.my/openapi
Admin
Open Election API is a programmatic interface to ElectionData.MY's comprehensive dataset of...
Tokens:7,952
Snippets:76
Trust Score:6.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Sample API Request

Source: https://electiondata.my/openapi/authentication

A complete example of an authenticated GET request using cURL.

```bash
curl -X GET "https://api.electiondata.my/v1/candidates?id=CMVBA" \
   -H "Authorization: Bearer your-api-key-here"
```

--------------------------------

### GET /v1/elections/stats

Source: https://electiondata.my/openapi/endpoints/elections

Retrieves aggregate turnout and rejection statistics for a specific election and state.

```APIDOC
## GET /v1/elections/stats

### Description
Pass the state and election identifier to get aggregate turnout and rejection statistics for the entire election.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/elections/stats

### Parameters
#### Query Parameters
- **state** (string) - Required - State or aggregation scope, e.g. 'Malaysia' or 'Selangor'.
- **election** (string) - Required - Election identifier, e.g. 'GE-15' or 'SE-15'.

### Request Example
curl -X GET "https://api.electiondata.my/v1/elections/stats?state=Malaysia&election=GE-15" -H "Authorization: Bearer <your-api-key>"

### Response
#### Success Response (200)
- **stats** (array) - Contains a single aggregate statistics object:
  - **voters_total** (integer) - Total number of registered voters.
  - **voter_turnout** (integer) - Total votes cast, including rejected votes.
  - **voter_turnout_perc** (float) - Turnout as a percentage of registered voters.
  - **votes_rejected** (integer) - Total number of votes rejected.
  - **votes_rejected_perc** (float) - Rejected votes as a percentage of total ballots cast.
  - **n_candidates** (integer) - Total number of candidates who contested.
```

--------------------------------

### GET /v1/parties/dropdown

Source: https://electiondata.my/openapi/endpoints/parties

Retrieves a list of parties for use in dropdown selections.

```APIDOC
## GET /v1/parties/dropdown

### Description
Retrieves a list of parties to populate dropdown menus for entity, state, and election type selection.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/parties/dropdown
```

--------------------------------

### GET /v1/elections/dropdown

Source: https://electiondata.my/openapi/endpoints/elections

Fetches the list of available elections and states for use in dropdown menus.

```APIDOC
## GET /v1/elections/dropdown

### Description
Fetches the list of elections to populate dropdown menus. This data is used to sync selections across other tabs.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/elections/dropdown
```

--------------------------------

### GET /v1/seats/dropdown

Source: https://electiondata.my/openapi/endpoints/seats

Retrieves a dropdown list of seats based on lineage preferences.

```APIDOC
## GET /v1/seats/dropdown

### Description
Retrieves a list of seats for use in a dropdown menu, allowing users to select a seat based on their lineage preference.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/seats/dropdown
```

--------------------------------

### Example Error Response

Source: https://electiondata.my/openapi/errors

The standard JSON structure returned when a request fails, such as when a version prefix is missing.

```http
HTTP/2 400  {   "error": "API version required. Use /vN/ prefix, e.g. /v1/candidates" }
```

--------------------------------

### GET /v1/parties/dropdown

Source: https://electiondata.my/openapi/endpoints/parties

Fetches a list of all parties and coalitions that have ever contested an election, including their UIDs and canonical mappings.

```APIDOC
## GET /v1/parties/dropdown

### Description
Fetches the full list of every entity that has ever contested an election, along with its canonical UID. This list is useful for building search dropdowns.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/parties/dropdown

### Response
#### Success Response (200)
- **data** (array) - An array of party/coalition objects.
  - **type** (string) - 'party' or 'coalition'.
  - **uid** (string) - The historical UID this entry represents.
  - **maps_to** (string) - The canonical current UID.
  - **acronym** (string) - Short name as used at the time.
  - **name_en** (string) - Full English name.
  - **name_bm** (string) - Full Bahasa Malaysia name.
```

--------------------------------

### Get election summary statistics

Source: https://electiondata.my/openapi/endpoints/elections

Retrieves aggregate turnout and rejection statistics for a specific election and state.

```cURL
curl -X GET "https://api.electiondata.my/v1/elections/stats?state=Malaysia&election=GE-15" \
   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Get list of candidates

Source: https://electiondata.my/openapi/endpoints/candidates

Retrieves a list of all candidates who have contested an election. Recommended to cache this data for the duration of a session.

```cURL
curl -X GET "https://api.electiondata.my/v1/candidates/dropdown" \
   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### GET /results

Source: https://electiondata.my/openapi/endpoints/results

Retrieves complete details for a specific contest. Requires a Bearer token for authentication.

```APIDOC
## GET /results

### Description
Retrieves the complete details for a single contest. This endpoint is designed to be used to zoom into a specific contest after identifying it via other API endpoints.

### Method
GET

### Endpoint
/results

### Authentication
- **Authorization** (header) - Required - Bearer token
```

--------------------------------

### GET /v1/candidates/dropdown

Source: https://electiondata.my/openapi/endpoints/candidates

Retrieves a list of all candidates who have contested an election, including their unique IDs, names, and contest statistics.

```APIDOC
## GET /v1/candidates/dropdown

### Description
Retrieves a list of every candidate who has ever contested an election, along with their unique ID. This list is recommended for caching as it is updated only after nomination days.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/candidates/dropdown

### Response
#### Success Response (200)
- **uid** (string) - Unique candidate identifier.
- **name** (string) - Candidate's full name.
- **c** (integer) - Total contests stood in.
- **w** (integer) - Total contests won.
- **l** (integer) - Total contests lost.
```

--------------------------------

### GET /v1/seats/results

Source: https://electiondata.my/openapi/endpoints/seats

Retrieves the electoral history for a specific seat using its slug.

```APIDOC
## GET /v1/seats/results

### Description
Retrieves the electoral history for a specific seat. Optionally includes boundary-change events via the lineage parameter.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/seats/results

### Parameters
#### Query Parameters
- **slug** (string) - Required - Unique seat identifier from the dropdown
- **lineage** (boolean) - Optional - Set to 'true' to include ancestral results and boundary-change events

### Response
#### Success Response (200)
- **results** (array) - List of election results or boundary-change events
  - **election_name** (string) - Human-readable election name
  - **seat** (string) - Seat name as it appeared on the ballot
  - **state** (string) - State the seat belongs to
  - **date** (date) - Polling day or redelineation date (YYYY-MM-DD)
  - **party** (string) - Acronym of the winning party
  - **party_uid** (string) - Unique party identifier
  - **coalition** (string) - Winning party's coalition
  - **coalition_uid** (number) - Unique coalition identifier
  - **name** (string) - Name of the winning candidate
  - **majority** (integer) - Winning majority in votes
  - **majority_perc** (float) - Majority as a percentage of valid votes
  - **voter_turnout** (integer) - Total votes cast
  - **voter_turnout_perc** (float) - Turnout as a percentage of registered voters
  - **change_en** (string) - English description of boundary change
  - **change_ms** (string) - Bahasa Malaysia description of boundary change
```

--------------------------------

### GET /v1/byelections

Source: https://electiondata.my/openapi/endpoints/byelections

Retrieves a list of every by-election (PRK) held in Malaysia from 1957 to the present.

```APIDOC
## GET /v1/byelections

### Description
Retrieves a list of every by-election (PRK) held in Malaysia from 1957 to the present. The list is ordered from the most recent to the oldest.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/byelections

### Response
#### Success Response (200)
- **data** (array) - An array of by-election objects containing:
  - **seat** (string) - Constituency identifier.
  - **state** (string) - State name.
  - **date** (date) - Polling day in ISO 8601 format (YYYY-MM-DD).
  - **name** (string) - Winner's full name.
  - **party_uid** (string) - Unique party identifier.
  - **party** (string) - Acronym of the winning party.
  - **coalition_uid** (integer) - Numeric coalition identifier.
  - **coalition** (string) - Coalition name.
  - **voters_total** (integer) - Total number of registered voters.
  - **voter_turnout** (integer) - Total votes cast.
  - **voter_turnout_perc** (float) - Turnout as a percentage of registered voters.
  - **votes_rejected** (integer) - Number of votes rejected.
  - **votes_rejected_perc** (float) - Rejected votes as a percentage of total ballots cast.
  - **majority** (integer) - Winning margin.
  - **majority_perc** (float) - Majority as a percentage of total valid votes.
```

--------------------------------

### GET /v1/seats/dropdown

Source: https://electiondata.my/openapi/endpoints/seats

Fetches the full list of current seats and their slugs for use in dropdown menus.

```APIDOC
## GET /v1/seats/dropdown

### Description
Fetches the full list of current seats and their slugs. It is recommended to cache this data for the duration of a session.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/seats/dropdown

### Response
#### Success Response (200)
- **seats** (array) - List of seat objects
  - **seat** (string) - Full seat name including number and state
  - **slug** (string) - URL-safe unique identifier for the seat
  - **type** (string) - 'parlimen' or 'dun'
```

--------------------------------

### GET /v1/parties/results

Source: https://electiondata.my/openapi/endpoints/parties

Retrieves the time-series of election results for a specific party or coalition entity.

```APIDOC
## GET /v1/parties/results

### Description
Retrieves the time-series of election results for a specific party or coalition entity based on the provided UID, state, and election type.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/parties/results

### Parameters
#### Query Parameters
- **type** (string) - Required - Entity type: 'party' or 'coalition'.
- **uid** (string) - Required - Unique identifier for the entity (e.g., '046-AMANAH').
- **state** (string) - Required - One of 18 valid state values (e.g., 'Selangor', 'Sabah', 'Malaysia').
- **election_type** (string) - Required - 'parlimen' for parliamentary or 'dun' for state assembly elections.

### Request Example
curl -X GET "https://api.electiondata.my/v1/parties/results?type=party&uid=046-AMANAH&state=Selangor&election_type=parlimen" -H "Authorization: Bearer <your-api-key>"

### Response
#### Success Response (200)
- **results** (array) - List of election result objects ordered from most recent to oldest.

#### Response Example
{
  "results": [
    {
      "party_type": "party",
      "state": "Selangor",
      "type": "parlimen",
      "known_as_uid": "046-AMANAH",
      "known_as": "AMANAH",
      "coalition": "PH",
      "coalition_uid": "007-PH",
      "election_name": "GE-15",
      "date": "2022-11-19",
      "seats_contested": 9,
      "seats_won": 6,
      "seats_total": 22,
      "seats_contested_perc": 40.9,
      "seats_won_perc": 27.3,
      "votes": 250000,
      "votes_perc": 12.5
    }
  ]
}
```

--------------------------------

### GET /v1/results

Source: https://electiondata.my/openapi/endpoints/results

Retrieves the full contest result for a specific seat, state, and date.

```APIDOC
## GET https://api.electiondata.my/v1/results

### Description
Retrieves the full contest result, including candidate ballots and aggregate statistics, for a specific seat, state, and date.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/results

### Parameters
#### Query Parameters
- **seat** (string) - Required - Constituency identifier (e.g., 'P.001 Padang Besar').
- **state** (string) - Required - State name (e.g., 'Perlis').
- **date** (string) - Required - Polling day in ISO 8601 format (YYYY-MM-DD).

### Response
#### Success Response (200)
- **ballot** (array) - List of candidates ordered by votes received.
- **stats** (array) - Aggregate statistics for the contest.

#### Error Handling
- **400 Bad Request**: Returned if any mandatory parameter is missing or if the date format is invalid.
- **404 Not Found**: Returned if the combination of parameters does not correspond to a real contest.
```

--------------------------------

### GET /v1/elections/by_seat

Source: https://electiondata.my/openapi/endpoints/elections

Retrieves election results by seat for a specified state and election identifier.

```APIDOC
## GET /v1/elections/by_seat

### Description
Pass the state and election identifier to get constituency data for that election.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/elections/by_seat

### Parameters
#### Query Parameters
- **state** (string) - Required - State or aggregation scope, e.g. 'Malaysia' or 'Selangor'.
- **election** (string) - Required - Election identifier, e.g. 'GE-15' or 'SE-15'.

### Request Example
curl -X GET "https://api.electiondata.my/v1/elections/by_seat?state=Malaysia&election=GE-15" -H "Authorization: Bearer <your-api-key>"

### Response
#### Success Response (200)
- **by_seat** (array) - Array of seat results.
  - **seat** (string) - Constituency identifier.
  - **state** (string) - The state parameter echoed back.
  - **date** (date) - Polling day in ISO 8601 format.
  - **name** (string) - Winner's full name.
  - **party** (string) - Acronym of the winning party.
  - **party_uid** (string) - Unique identifier for the winning party.
  - **coalition** (string) - Coalition of the winning party.
  - **coalition_uid** (integer) - Numeric coalition identifier.
  - **party_lost** (string[]) - Acronyms of parties that lost.
  - **party_lost_uid** (string[]) - Unique identifiers for the losing parties.
  - **coalition_lost** (string[]) - Coalitions represented by the losing parties.
  - **coalition_lost_uid** (integer[]) - Numeric identifiers for the losing coalitions.
  - **n_candidates** (integer) - Total number of candidates.
  - **voters_total** (integer) - Total number of registered voters.
  - **voter_turnout** (integer) - Total votes cast.
  - **voter_turnout_perc** (float) - Turnout as a percentage.
  - **majority** (integer) - Winning margin.
  - **majority_perc** (float) - Majority as a percentage.
  - **votes_rejected** (integer) - Number of votes rejected.
  - **votes_rejected_perc** (float) - Rejected votes as a percentage.
```

--------------------------------

### GET /elections/dropdown

Source: https://electiondata.my/openapi/endpoints/elections

Retrieves a list of all general and state elections available in the database. The returned election identifiers are required for subsequent data endpoints.

```APIDOC
## GET /elections/dropdown

### Description
Retrieves a list of all general and state elections available in the database. The returned election identifiers are required for subsequent data endpoints.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/elections/dropdown

### Response
#### Success Response (200)
- **elections** (array) - An array of election objects.
  - **state** (string) - State or aggregation scope.
  - **type** (string) - 'parlimen' for parliamentary or 'dun' for state assembly.
  - **election** (string) - Election identifier.
  - **date** (date) - Polling day in ISO 8601 format.
```

--------------------------------

### Get single candidate details

Source: https://electiondata.my/openapi/endpoints/candidates

Retrieves election results for a specific candidate using their unique identifier. The uid parameter is mandatory.

```cURL
curl -X GET "https://api.electiondata.my/v1/candidates?uid=CMVBA" \
   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### GET /v1/candidates

Source: https://electiondata.my/openapi/endpoints/candidates

Retrieves detailed election results for a specific candidate using their unique identifier.

```APIDOC
## GET /v1/candidates

### Description
Retrieves the election results for a specific candidate based on their unique identifier.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/candidates

### Parameters
#### Query Parameters
- **uid** (string) - Required - Unique identifier derived from the dropdown endpoint.

### Response
#### Success Response (200)
- **name** (string) - Candidate's full name.
- **election_name** (string) - Human-readable election name.
- **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.
- **state** (string) - State of the constituency.
- **party** (string) - Acronym of the candidate's party.
- **party_uid** (string) - Unique party identifier.
- **coalition** (string) - Coalitional affiliation of the party.
- **coalition_uid** (number) - Unique coalition identifier.
- **votes** (integer) - Total votes received by the candidate.
- **votes_perc** (float) - Percentage of valid votes received.
- **result** (string) - One of: 'won', 'won_uncontested', 'lost', or 'lost_deposit'.
```

--------------------------------

### GET /v1/elections/by_party

Source: https://electiondata.my/openapi/endpoints/elections

Retrieves party-level vote and seat aggregates based on the provided state and election identifier.

```APIDOC
## GET /v1/elections/by_party

### Description
Retrieves party-level vote and seat aggregates for a specific state and election. Results are ordered by votes received in descending order.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/elections/by_party

### Parameters
#### Query Parameters
- **state** (string) - Required - State or aggregation scope (e.g., 'Malaysia', 'Selangor').
- **election** (string) - Required - Election identifier (e.g., 'GE-15', 'SE-15').

### Request Example
curl -X GET "https://api.electiondata.my/v1/elections/by_party?state=Malaysia&election=GE-15" -H "Authorization: Bearer <your-api-key>"

### Response
#### Success Response (200)
- **by_party** (array) - Array of party results.
  - **party_uid** (string) - Unique party identifier.
  - **party** (string) - Party acronym.
  - **coalition** (string) - Coalition name or 'ALONE'.
  - **coalition_uid** (string) - Unique coalition identifier or '0'.
  - **seats_contested** (integer) - Number of seats contested.
  - **seats_won** (integer) - Number of seats won.
  - **seats_total** (integer) - Total seats available.
  - **seats_contested_perc** (float) - Percentage of seats contested.
  - **seats_won_perc** (float) - Percentage of seats won.
  - **votes** (integer) - Total votes received.
  - **votes_total** (integer) - Total valid votes cast.
  - **votes_perc** (float) - Percentage of total votes.
```

--------------------------------

### GET /v1/results

Source: https://electiondata.my/openapi/endpoints/results

Retrieves election results based on the specified seat, state, and date parameters.

```APIDOC
## GET /v1/results

### Description
Retrieves election results for a specific seat, state, and date.

### Method
GET

### Endpoint
https://api.electiondata.my/v1/results

### Parameters
#### Query Parameters
- **seat** (string) - Required - The name of the seat (e.g., P.001 Padang Besar)
- **state** (string) - Required - The name of the state (e.g., Perlis)
- **date** (string) - Required - The date of the election (YYYY-MM-DD)
```

--------------------------------

### Retrieve party results via cURL

Source: https://electiondata.my/openapi/endpoints/parties

Fetches election results for a specific entity using a GET request with required query parameters and an authorization header.

```cURL
curl -X GET "https://api.electiondata.my/v1/parties/results?type=party&uid=046-AMANAH&state=Selangor&election_type=parlimen" \   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Fetch list of parties

Source: https://electiondata.my/openapi/endpoints/parties

Retrieves a list of all parties and coalitions that have contested an election. Cache this data as it only updates after new elections.

```cURL
curl -X GET "https://api.electiondata.my/v1/parties/dropdown" \
   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Retrieve contest results via cURL

Source: https://electiondata.my/openapi/endpoints/results

Use this cURL command to fetch contest results by providing the seat, state, and date as query parameters with an authorization header.

```bash
curl -X GET "https://api.electiondata.my/v1/results?seat=P.001%20Padang%20Besar&state=Perlis&date=2022-11-19" \
   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Fetch election dropdown data

Source: https://electiondata.my/openapi/endpoints/elections

Retrieves the list of available elections and states for use in UI components.

```HTTP
GET`https://api.electiondata.my/v1/elections/dropdown`
```

--------------------------------

### Fetch election list via cURL

Source: https://electiondata.my/openapi/endpoints/elections

Retrieve all available general and state elections. Cache this response to optimize performance.

```cURL
curl -X GET "https://api.electiondata.my/v1/elections/dropdown" \
   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Fetch seat results with lineage

Source: https://electiondata.my/openapi/endpoints/seats

Retrieves electoral history including boundary-change events by setting the lineage parameter to true.

```cURL
curl -X GET "https://api.electiondata.my/v1/seats/results?slug=p001-padang-besar-perlis&lineage=true" \   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Authorization Header Format

Source: https://electiondata.my/openapi/authentication

The required format for the Authorization header in API requests.

```http
Authorization: Bearer <your-api-key>
```

--------------------------------

### Retrieve election results by seat via cURL

Source: https://electiondata.my/openapi/endpoints/elections

Use this cURL command to fetch constituency results by providing the state and election parameters along with your API key.

```bash
curl -X GET "https://api.electiondata.my/v1/elections/by_seat?state=Malaysia&election=GE-15" \   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Retrieve list of by-elections via cURL

Source: https://electiondata.my/openapi/endpoints/byelections

Fetches the complete list of historical by-elections. Requires a valid Bearer token in the Authorization header.

```cURL
curl -X GET "https://api.electiondata.my/v1/byelections" \
   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Authentication via Authorization Header

Source: https://electiondata.my/openapi/authentication

All requests to the ElectionData.MY API must be authenticated using a Bearer token in the Authorization header.

```APIDOC
## Authentication

### Description
All requests to the ElectionData.MY API must be authenticated using a Bearer token in the `Authorization` header. Requests without a valid API key will receive a `401 Unauthorized` response.

### Header
- **Authorization** (string) - Required - The value must be `Bearer <your-api-key>`

### Request Example
```bash
curl -X GET "https://api.electiondata.my/v1/candidates?id=CMVBA" \
  -H "Authorization: Bearer your-api-key-here"
```
```

--------------------------------

### Fetch single seat results

Source: https://electiondata.my/openapi/endpoints/seats

Retrieves electoral history for a specific seat using its slug. The slug parameter is mandatory.

```cURL
curl -X GET "https://api.electiondata.my/v1/seats/results?slug=p001-padang-besar-perlis" \   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Fetch list of seats

Source: https://electiondata.my/openapi/endpoints/seats

Retrieves the full list of current seats and their slugs. Caching this data is recommended as it only updates when electoral boundaries change.

```cURL
curl -X GET "https://api.electiondata.my/v1/seats/dropdown" \   -H "Authorization: Bearer <your-api-key>"
```

--------------------------------

### Error Response Format

Source: https://electiondata.my/openapi/errors

All error responses follow a consistent structure containing a JSON object with an error field.

```APIDOC
### Error Response Format

All error responses return the relevant HTTP status code along with a JSON body containing a single `error` field.

#### Response Example
```json
{
  "error": "API version required. Use /vN/ prefix, e.g. /v1/candidates"
}
```
```
Tokens:
Raw