<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 实时公交到站

> 输入城市和站名，实时查询该站各公交线路的到站信息：车牌、预计到站时间、剩余站数、票价、终点方向。

覆盖全国数百城市，支持双向查询（direction）。数据实时、结构清晰，适用于出行助手、公交小程序、生活服务集成等场景。完全免费。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `bus-realtime` |
| 接口名称 | 实时公交到站 |
| 接口地址 | `https://v1.apizero.cn/api/bus-realtime` |
| 请求方法 | `POST` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 1000 次（已认证用户） |
| 匿名每日额度 | 500 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

登录用户每日 1000 次免费（QPS 10），匿名用户每日 500 次（QPS 5）。可选携带 API Key（Authorization: Bearer <key>）享更高额度。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `city` | `string` | 是 | 城市名 | `长沙` |
| `station` | `string` | 是 | 站名或关键词（兼容别名 line） | `五一广场` |
| `direction` | `int` | 否 | 方向：1=默认，2=反方向 | `1` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Content-Type` | `string` | 是 | 请求体格式 | — |

## 5. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

```bash
curl -X POST "https://v1.apizero.cn/api/bus-realtime" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "长沙",
  "station": "五一广场",
  "direction": "1"
}'
```

### Python

```python
import requests

resp = requests.request(
    "POST",
    "https://v1.apizero.cn/api/bus-realtime",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
    "city": "长沙",
    "station": "五一广场",
    "direction": "1",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const res = await fetch("https://v1.apizero.cn/api/bus-realtime", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "city": "长沙",
    "station": "五一广场",
    "direction": "1"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"city":"长沙","station":"五一广场","direction":"1"}`)
	req, _ := http.NewRequest("POST", "https://v1.apizero.cn/api/bus-realtime", bytes.NewBuffer(body))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}
```

### PHP

```php
<?php
$payload = json_encode([
    "city" => "长沙",
    "station" => "五一广场",
    "direction" => "1",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://v1.apizero.cn/api/bus-realtime");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        "X-Api-Key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `city` | `string` | 查询城市 | — |
| `station` | `string` | 规范化站名 | — |
| `direction` | `number` | 方向（1/2） | — |
| `line_count` | `number` | 线路数量 | — |
| `lines` | `array` | 线路列表：line 线路名 / price 票价 / terminal 终点方向 / bus_count 在途车数 / buses 车辆数组 | — |
| `lines[].buses` | `array` | 每辆车：bus_id 车牌 / arrival_time 预计到站 / arrival_timestamp 时间戳(ms) / travel_minutes 预计分钟 / stops_remaining 剩余站数 / status 状态(即将到站/已过站/n站) | — |
| `updated_at` | `string` | 数据生成时间 | — |

## 7. 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "city": "长沙",
    "station": "五一广场",
    "direction": 1,
    "line_count": 2,
    "lines": [
      {
        "line": "401路",
        "price": "2",
        "terminal": "汽车西站",
        "bus_count": 1,
        "buses": [
          { "bus_id": "湘A02882D", "arrival_time": "2026-07-01 12:34", "arrival_timestamp": 1751344440000, "travel_minutes": 6, "stops_remaining": 5, "status": "5站" }
        ]
      }
    ],
    "updated_at": "2026-07-01 12:30:00"
  },
  "request_id": "a1b2c3d4"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `VALIDATION_ERROR` | 缺少 city/station，或未找到该城市 / 车站 |
| `5020` | `UPSTREAM_ERROR` | 实时公交服务暂不可用，请稍后再试 |
| `5021` | `UPSTREAM_INVALID` | 实时公交数据格式异常 |

## 9. 变更日志

- **v1.0** (2026-07-01)
  - 首次上线：按城市+站名查询实时到站，支持双向、按线路分组返回车牌/到站时间/剩余站数/票价。

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/bus-realtime`

Source: `https://apizero.cn/aidocs/bus-realtime/raw.md`
Last updated: 2026-07-01T11:57:13+08:00