# API Documentation

## Overview

This API provides access to voting data based on specified areas and years in Taiwan. It returns detailed information about vote counts, candidates, and vote rates in various administrative divisions such as counties, cities, townships, and villages.

## Endpoint

- **URL**: `POST http://wwweb2024.csie.io:52000/api.php`
- **Method**: `POST`

## Authentication

- **Type**: Token Authentication
- **Token**: `h6kcdm9pazx7j9xd`
- **Header**: Include the token in the request header as follows:
`Authorization: Token h6kcdm9pazx7j9xd`

## Request Format

- **Headers**:
- Content-Type: `application/json`
- Authorization: `Token h6kcdm9pazx7j9xd`
- **Body**:
- `area`: (String) The name of the area (e.g., "臺灣", "雲林縣").
- `year`: (Integer) The year for which voting data is requested. Valid years are 2016, 2020, and 2024. If an invalid year is provided, the system will default to 2024.

Example Request Body:

{
  "area": "臺灣",
  "year": 2024
}

## Response Format

The response will be a JSON object containing an array of objects. Each object represents voting data for a specific administrative division.

- **id**: (Integer) Unique identifier for the data entry.
- **full_district_name**: (String) The full name of the district (e.g., "南投縣").
- **county_name**: (String) Name of the county.
- **township_name**: (String) Name of the township ("-” if not applicable).
- **village_name**: (String) Name of the village ("-” if not applicable).
- **candidate[1-3]_votes**: (Integer) Number of votes for candidates 1 to 3.
- **candidate[1-3]_name**: (String) Names of the candidates (in Traditional Chinese).
- **candidate[1-3]_color**: (String) Associated color for each candidate.
- **candidate[1-3]_vote_rate**: (Float) Vote rate for each candidate.

Example Response Data:

[
    {
        "id": 1,
        "full_district_name": "南投縣",
        "county_name": "南投縣",
        "township_name": "-",
        "village_name": "-",
        "candidate1_votes": 74854,
        "candidate2_votes": 103279,
        "candidate3_votes": 109163,
        "candidate1_name": "柯文哲吳欣盈",
        "candidate2_name": "賴清德蕭美琴",
        "candidate3_name": "侯友宜趙少康",
        "candidate1_color": "white",
        "candidate2_color": "green",
        "candidate3_color": "blue",
        "candidate1_vote_rate": 0.2605,
        "candidate2_vote_rate": 0.3595,
        "candidate3_vote_rate": 0.38
    },
    ...
]

## Notes

When the `area` parameter is set to "臺灣", the API returns data for all counties and cities in Taiwan. If a specific county or city name is provided in the `area` parameter (e.g., "雲林縣"), the API returns data for the townships within that county or city. Data accuracy and completeness depend on the latest updates available to the API.

## Usage Examples

To retrieve voting data for Taiwan in 2024:

{
  "area": "臺灣",
  "year": 2024
}

To retrieve voting data for Yunlin County ("雲林縣") in 2020:

{
  "area": "雲林縣",
  "year": 2020
}

This API is a powerful tool for accessing detailed voting data across various levels of administrative divisions in Taiwan, offering insights into electoral trends and candidate performances.