API 文档

身份验证

所有端点均支持身份验证访问及公开访问。经过验证的请求享有更高的频率限制。

请通过以下请求头传递 API 密钥： X-API-Key 。切勿通过查询参数发送密钥。

请求示例

curl -H "X-API-Key: your_api_key_here" \
     https://coekaki.com/api/v1/results/latest

请求频率限制

访问级别	频率限制
公开访问（无需 API 密钥）	每分钟 100 次请求
已验证（使用 API 密钥）	每分钟 1,000 次请求

请求频率限制状态通过以下响应头返回： X-RateLimit-* 。

响应格式

所有响应均以统一结构返回 JSON：

{
  "data": [ ... ],
  "meta": {
    "total": 50,
    "page": 1,
    "per_page": 50,
    "last_page": 1
  }
}

每个响应均包含以下响应头： X-API-Version: v1 。

错误代码

HTTP 状态	代码	说明
401	INVALID_API_KEY	提供的 API 密钥无效。
404	NOT_FOUND	请求的资源不存在。
422	VALIDATION_ERROR	请求参数未通过验证。
429	RATE_LIMITED	请求过多，请降低频率后重试。

拥车证结果

GET /api/v1/results

以分页形式列出拥车证竞标结果，并支持可选筛选条件。

参数

参数	类型	说明
category	string	按类别筛选：A、B、C、D 或 E
from	date	开始日期（YYYY-MM-DD）
至	date	结束日期（YYYY-MM-DD）
page	integer	页码（默认：1）
per_page	integer	每页结果数（最多：200，默认：50）

示例

GET /api/v1/results?category=A&from=2025-01-01&to=2025-12-31

GET /api/v1/results/latest

获取所有类别最近一轮的竞标结果。

响应

{
  "data": [
    {
      "id": 1,
      "bidding_date": "2026-04-09",
      "bidding_round": 1,
      "category": "A",
      "quota_premium": 98000,
      "pqp": 95000,
      "bids_submitted": 2100,
      "bids_successful": 1850
    }
  ],
  "meta": { "total": 5, "bidding_date": "2026-04-09" }
}

GET /api/v1/results/{id}

通过数字 ID 获取单条拥车证结果；未找到时返回 404。

趋势

GET /api/v1/trends

按类别分组的历史拥车证溢价趋势，返回可用于图表的数据。

参数

参数	类型	说明
months	integer	回溯月数（1–120，默认：12）
category	string	筛选单一类别：A、B、C、D 或 E
from	date	开始日期（YYYY-MM-DD）
至	date	结束日期（YYYY-MM-DD）

GET /api/v1/trends/pqp

各类别的现行配额溢价（PQP）走势，包括拥车证溢价与 PQP 的差额。

历史数据不足或类别为 E 时，PQP 及其价差均为 null。E 类车辆按对应的 A–D 车辆类别续期。

接受与以下端点相同的参数： /trends.

竞标日程

GET /api/v1/schedule

列出所有竞标日程，按时间从新到旧排序。

GET /api/v1/schedule/upcoming

尚未开始的即将举行的竞标轮次。

GET /api/v1/schedule/current

获取当前正在进行的竞标轮次。若无进行中的竞标，则返回 data: null 。

响应（当前没有进行中的投标轮次）

{
  "data": null,
  "meta": {
    "is_live": false,
    "message": "No bidding exercise is currently live."
  }
}

注销车辆

GET /api/v1/deregistrations

以分页形式列出车辆注销数据，并支持筛选。

参数

参数	类型	说明
category	string	按类别筛选：A、B、C、D 或 E
from	date	开始日期（YYYY-MM-DD）
至	date	结束日期（YYYY-MM-DD）
per_page	integer	每页结果数（最多：200，默认：50）

GET /api/v1/deregistrations/latest

各类别最近一个月的注销数据（也可按以下参数筛选： category).

拥车证配额

GET /api/v1/quotas

以分页形式列出季度拥车证配额分配，并支持筛选。

参数

参数	类型	说明
category	string	按类别筛选：A、B、C、D 或 E
from	date	quarter_start 的开始日期（YYYY-MM-DD）
至	date	quarter_start 的结束日期（YYYY-MM-DD）
per_page	integer	每页结果数（最多：200，默认：50）

GET /api/v1/quotas/latest

当前季度的拥车证配额分配；若当前数据尚未公布，则返回最近一个季度的数据。

PQP 历史

GET /api/v1/pqp

现行配额溢价（PQP）历史记录，以及各期结果中拥车证溢价与 PQP 的差额。