tdx RESTful API 接口文档

基于 Gin 的通达信行情网关。入口：cmd/api，实现：extend/httpserver。

启动

本地调试

# 项目根目录
go run ./cmd/api

# 端口占用时
ADDR=:18080 go run ./cmd/api

Docker（对外提供 API）

# 构建并后台启动, 映射宿主机 8080
docker compose up -d --build

# 查看日志
docker compose logs -f tdx-api

# 本机验证
curl http://127.0.0.1:8080/health

# 局域网其它机器: http://<宿主机IP>:8080/health

仅构建镜像：

docker build -t tdx-api:latest .
docker run -d --name tdx-api -p 8080:8080 \
  -e GIN_MODE=release -e EXHQ=1 \
  -v tdx-data:/app/data \
  tdx-api:latest

容器需能访问公网通达信行情（TCP 7709 / 扩展 7727）。数据目录挂载到 /app/data（gbbq 缓存等）。

调用注意（常见“不通”原因）

1. 缺必填参数会返回 code=1 或 HTTP 400，不是没实现。例如 /quote 必须带 codes，/block/data 必须带 file。
2. 中文参数请 URL 编码，或用支持 UTF-8 的客户端（Apifox / Postman）。PowerShell/部分终端直接写 name=创业板指 可能乱码导致“未找到”。
3. 扩展行情 /ex/* 依赖独立服务器（7727）。cmd/api 默认 EXHQ=1 启用；若启动失败或你设了 EXHQ=0，这些路由不存在（404）。
4. 本地默认若 :8080 被占用，请用 ADDR=:18080 go run ./cmd/api，请求也要打到对应端口。

统一响应

成功

{
  "code": 0,
  "msg": "ok",
  "data": {}
}

失败

{
  "code": 1,
  "msg": "错误信息",
  "data": null
}

1. 首页与健康检查

curl "http://127.0.0.1:18080/health"

{
  "code": 0,
  "msg": "ok",
  "data": { "status": "running", "framework": "gin" }
}

2. 代码 / 数量

exchange：sh / sz / bj。

GET /search

按代码或名称模糊搜索，一次返回五类结果：个股、ETF、指数、概念板块、行业板块。全市场代码、指数成分、概念板块（block_gn.dat）和行业板块（tdxhy.cfg 归集）由后台每日 16:30 拉取并落盘，接口只读内存，避免每次现拉通达信。

curl "http://127.0.0.1:8088/search?q=茅台"
curl "http://127.0.0.1:8088/search?q=000001"
curl "http://127.0.0.1:8088/search?q=沪深300&members=1"
curl "http://127.0.0.1:8088/search?q=50&type=etf&limit=10"
curl "http://127.0.0.1:8088/search?q=锂电池&type=concept"
curl "http://127.0.0.1:8088/search?q=银行&type=industry&members=1"

{
  "code": 0,
  "msg": "ok",
  "data": {
    "q": "茅台",
    "stocks": [
      { "code": "600519", "full_code": "sh600519", "name": "贵州茅台", "market": 1 }
    ],
    "etfs": [],
    "indexes": [],
    "concepts": [],
    "industries": []
  }
}

指数命中示例（members=1）：

{
  "q": "沪深300",
  "stocks": [],
  "etfs": [],
  "indexes": [
    {
      "code": "000300",
      "full_code": "sh000300",
      "name": "沪深300",
      "source": "block_zs",
      "member_count": 300,
      "members": [
        { "code": "600519", "name": "贵州茅台" }
      ]
    }
  ],
  "concepts": [],
  "industries": []
}

说明：

• indexes 来自 /index/constituents 同源数据（block_zs + spblock）。用成分股代码/名称搜索时，也可能返回其所属指数。
• concepts 与 /block/concept 同源（block_gn.dat，source=block_gn）。index 为板块指数代码（如 880978），full_code 为带市场前缀的代码（如 sh880978）。
• industries 与 /block/industry 同源（tdxhy.cfg 按通达信新行业归集，source=tdxhy）。code 为行业码（Txxxx），index 为匹配到的 880xxx。
• 用成分股代码，或成分股名称精确匹配时，也会返回其所属概念、行业。已有旧索引文件会在启动后后台补拉这两类数据。

概念 / 行业命中示例（members=1）：

{
  "q": "锂电池",
  "stocks": [],
  "etfs": [],
  "indexes": [],
  "concepts": [
    {
      "name": "锂电池",
      "index": "880978",
      "full_code": "sh880978",
      "source": "block_gn",
      "member_count": 50,
      "members": [
        { "code": "300750", "name": "宁德时代" }
      ]
    }
  ],
  "industries": []
}

GET /market/concentration

全 A 股日线成交额集中度：当日成交额排名前 5% 股票的成交额合计 ÷ 全 A 总成交额。

增量逻辑

• 结果落盘：data/concentration/ashare_concentration.json（容器内 /app/data/concentration/ashare_concentration.json）
• 文件不存在时：服务启动后异步按月回补，起始日 2024-09-24
• 文件已存在：只补缺失交易日；交易日 16:00 自动计算当日并写入
• 可用 DISABLE_CONCENTRATION=1 关闭后台任务

curl "http://127.0.0.1:8088/market/concentration"
curl "http://127.0.0.1:8088/market/concentration?start=20240924&end=20241031"

{
  "code": 0,
  "msg": "ok",
  "data": {
    "version": 1,
    "top_pct": 0.05,
    "from": "20240924",
    "updated_at": "2026-08-03T16:05:00+08:00",
    "status": "idle",
    "points": [
      {
        "date": "20240924",
        "concentration": 0.3125,
        "total_amount": 1200000000000,
        "top_amount": 375000000000,
        "stock_count": 5100,
        "top_count": 255
      }
    ]
  }
}

status：idle / backfilling / updating / error；回补过程中 message 会显示进度。金额单位为元。

3. 行情 / 财务

GET /quote

实时五档买卖盘口。对应客户端 GetQuote。

价格单位均为元；成交量/五档量为手；成交额为元。

curl "http://127.0.0.1:8088/quote?codes=sz000001,sh600519"
curl "http://127.0.0.1:8088/quote?code=600519"
curl "http://127.0.0.1:8088/quote?codes=000001,600519"

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "market": 0,
      "code": "000001",
      "full_code": "sz000001",
      "name": "平安银行",
      "server_time": "113000",
      "last": 11.52,
      "open": 11.50,
      "high": 11.60,
      "low": 11.48,
      "price": 11.55,
      "volume": 123456,
      "amount": 142000000.0,
      "bid_vol": 100,
      "inner": 60000,
      "outer": 63456,
      "change": 0.03,
      "change_pct": 0.26,
      "bid": [
        { "price": 11.54, "volume": 200 },
        { "price": 11.53, "volume": 300 },
        { "price": 11.52, "volume": 400 },
        { "price": 11.51, "volume": 500 },
        { "price": 11.50, "volume": 600 }
      ],
      "ask": [
        { "price": 11.55, "volume": 180 },
        { "price": 11.56, "volume": 220 },
        { "price": 11.57, "volume": 260 },
        { "price": 11.58, "volume": 300 },
        { "price": 11.59, "volume": 340 }
      ]
    }
  ]
}

字段说明：bid 买1→买5，ask 卖1→卖5；change / change_pct 相对昨收。

4. 分时 / 成交

date 格式：YYYYMMDD。

5. K 线（股票）

复权参数 fq（个股 K 线）

只复权 OHLC/昨收，成交量与成交额不复权。依赖 gbbq 股本变迁数据。

type 对照

# 默认前复权
curl "http://127.0.0.1:18080/kline/day?code=sh600519&start=0&count=5"
# 后复权 / 不复权
curl "http://127.0.0.1:18080/kline/day?code=sh600519&start=0&count=5&fq=hfq"
curl "http://127.0.0.1:18080/kline/day?code=sh600519&start=0&count=5&fq=raw"

个股 K 线每根额外返回 Turnover（换手率，单位 %），按当日流通股本计算：成交量(股) / 流通股本 × 100（成交量字段 Volume 为手，内部按 ×100 换算）。无股本数据时为 0。

{
  "code": 0,
  "msg": "ok",
  "data": {
    "Count": 1,
    "List": [
      {
        "Last": 11630,
        "Open": 11630,
        "High": 11700,
        "Low": 11500,
        "Close": 11650,
        "Volume": 2024978,
        "Amount": 2318839808000,
        "Time": "2026-07-31T15:00:00+08:00",
        "Turnover": 1.05
      }
    ]
  }
}

6. 指数 K 线

指数代码示例：sz399006（创业板指）、sh000300（沪深300）。

7. 指数成分（推荐）

通达信把指数成分拆在两份文件里：

请优先使用合并接口，不要只用 /spblock（其中没有沪深300）。

GET /index/constituents

curl "http://127.0.0.1:18080/index/constituents"
curl "http://127.0.0.1:18080/index/constituents?name=创业板指"
curl "http://127.0.0.1:18080/index/constituents?name=沪深300"
curl "http://127.0.0.1:18080/index/constituents?name=中证2000"

data 字段

{
  "code": 0,
  "msg": "ok",
  "data": {
    "name": "创业板指",
    "code": "399006",
    "codes": [
      { "code": "300001", "name": "特锐德" },
      { "code": "300002", "name": "神州泰岳" }
    ],
    "source": "block_zs"
  }
}

说明：

• 同名多市场指数代码优先上证（如沪深300 → 000300 而非 399300）。
• 部分指数（如中证2000）在通达信代码表中无标准指数码时，code 可能为空，但 codes 成分仍完整。

GET /spblock

curl "http://127.0.0.1:18080/spblock"
curl "http://127.0.0.1:18080/spblock?name=中证2000"

返回原始专业板块列表，codes 为字符串数组（7 字符：市场标志 + 6 位代码），不含中文名、不含沪深300。

8. 板块成分 / 行业归属

推荐：概念 / 行业专用接口

# 全部概念板块+成分
curl "http://127.0.0.1:18080/block/concept"
# 仅概念列表(不含成分明细)
curl "http://127.0.0.1:18080/block/concept?codes=0"
# 单个概念
curl "http://127.0.0.1:18080/block/concept?name=锂电池"

# 全部行业板块+成分
curl "http://127.0.0.1:18080/block/industry"
curl "http://127.0.0.1:18080/block/industry?name=银行"
curl "http://127.0.0.1:18080/block/industry?codes=0"

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "name": "银行",
      "code": "T1001",
      "index": "88047x",
      "type": 2,
      "count": 42,
      "codes": [
        { "code": "000001", "name": "平安银行" },
        { "code": "600036", "name": "招商银行" }
      ]
    }
  ]
}

说明：

• 概念：来自 block_gn.dat + tdxzs 回填指数 id。
• 行业：多数行情服务器无 block_hy.dat，本接口用 tdxhy.cfg 按通达信新行业码归集；code 为 Txxxx，name 来自 incon.dat，index 为匹配到的 880xxx。

GET /block/data · GET /block/data/index（通用）

curl "http://127.0.0.1:18080/block/data/index?file=gn"
curl "http://127.0.0.1:18080/block/data?file=fg"

GET /tdx/hy

全市场通达信新行业 + 申万行业归属；行业码经 incon.dat 翻译中文名。

curl "http://127.0.0.1:18080/tdx/hy?code=000001"
curl "http://127.0.0.1:18080/tdx/hy?code=sh600519"

{
  "code": 0,
  "msg": "ok",
  "data": {
    "market": 0,
    "code": "000001",
    "name": "平安银行",
    "tdx_hy": "T1001",
    "tdx_hy_name": "银行",
    "sw_hy": "X500102",
    "sw_hy_name": "股份制银行"
  }
}

9. 个股统计 / 资金流向

对应客户端：GetTdxStat / GetTdxStat2。数据来自 zhb.zip 内 tdxstat.cfg / tdxstat2.cfg（全市场盘后逐股）。默认只返回已核验字段；传 fields=1 可附带全部原始列。

GET /tdx/stat

个股综合统计：市盈 TTM/静态市盈、股息率、涨跌幅、连涨连跌天数、区间涨跌幅（5/10/20/60 日 / YTD）。

curl "http://127.0.0.1:18080/tdx/stat?code=sh600519"
curl "http://127.0.0.1:18080/tdx/stat?code=600519&fields=1"

{
  "code": 0,
  "msg": "ok",
  "data": {
    "market": 1,
    "code": "600519",
    "name": "贵州茅台",
    "date": "20260801",
    "pe_ttm": 20.5,
    "pe_static": 21.1,
    "div_yield": 3.2,
    "trend_days": 2,
    "change_pct": 0.85,
    "chg5": 1.2,
    "chg10": -0.3,
    "chg20": 2.1,
    "chg60": 5.6,
    "chg_ytd": 8.9
  }
}

GET /tdx/stat2

个股资金流向相关字段 + 所属/领涨板块指数代码；板块名经 tdxzs.cfg 翻译。

curl "http://127.0.0.1:18080/tdx/stat2?code=000001"

{
  "code": 0,
  "msg": "ok",
  "data": {
    "market": 0,
    "code": "000001",
    "name": "平安银行",
    "date": "20260801",
    "amount": 123456.78,
    "amount_prev": 98765.43,
    "ipo_price": 19.0,
    "high_52w": 13.5,
    "low_52w": 9.8,
    "block_index": "880515",
    "block_name": "银行"
  }
}

不传 code 时返回全市场数组。

10. 其它板块 / 报表文件

11. 扩展行情

cmd/api 默认已启用（EXHQ=1）。设 EXHQ=0 时 /ex/* 不注册（404）。扩展行情连的是 7727 端口，个别节点可能超时，属上游网络问题。

常用 market（节选）

完整列表：GET /ex/markets。

示例：沪金（上海期货黄金）

通达信里「沪金」对应 上海期货 market=30，常用代码：

# 市场列表 / 品种数量
curl "http://127.0.0.1:8088/ex/markets"
curl "http://127.0.0.1:8088/ex/count"

# 品种分页（全市场很大，按需翻页）
curl "http://127.0.0.1:8088/ex/instruments?start=0&count=50"

# 沪金主连 — 实时报价
curl "http://127.0.0.1:8088/ex/quote?market=30&code=AUL8"

# 沪金具体合约
curl "http://127.0.0.1:8088/ex/quote?market=30&code=AU2608"

# 沪金主连 — 分时 / 日K / 分笔
curl "http://127.0.0.1:8088/ex/minute?market=30&code=AUL8"
curl "http://127.0.0.1:8088/ex/bars?category=9&market=30&code=AUL8&start=0&count=20"
curl "http://127.0.0.1:8088/ex/trade?market=30&code=AUL8&start=0&count=30"

# 历史分时 / 历史分笔 / 日期区间K（date=YYYYMMDD）
curl "http://127.0.0.1:8088/ex/minute/hist?market=30&code=AUL8&date=20260731"
curl "http://127.0.0.1:8088/ex/trade/hist?market=30&code=AUL8&date=20260731&start=0&count=50"
curl "http://127.0.0.1:8088/ex/bars/range?market=30&code=AUL8&date=20260701&date2=20260731"

# 上期所报价列表（category=3 表示期货）
curl "http://127.0.0.1:8088/ex/quote_list?market=30&category=3&start=0&count=20"

# 上海黄金所现货（不是期货沪金）
curl "http://127.0.0.1:8088/ex/quote?market=46&code=Au99.99"

/ex/quote 返回示例（字段节选）：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "market": 30,
    "code": "AUL8",
    "preClose": 891.92,
    "open": 882.06,
    "high": 887.58,
    "low": 878.10,
    "price": 886.82,
    "chiCang": 181243,
    "zongLiang": 178245
  }
}

本地 go run 时把端口改成你的 ADDR（如 18080）。Docker 默认映射见 docker-compose.yml（当前为 8088）。

通用参数

相关文件