前言：在量化投资与海外行情分析的需求日益增长的当下，获取稳定可靠的韩国股市数据成为了不少开发者的痛点。韩国市场拥有KOSPI（主板）和KOSDAQ（创业板）两大重要指数，数据接口却相对小众。本文将记录一次使用第三方聚合API对接韩国股票数据的完整过程，涵盖RESTful接口调用与WebSocket实时推送，代码开源，仅做技术分享。
一、背景介绍
在开发一款面向亚太市场的行情看板时，我们需要集成韩国证券交易所（KRX）的数据。传统的爬虫方案由于反爬严格且维护成本高，最终选择了使用封装好的金融数据API服务。
本文使用的接口提供了标准的Restful风格和WebSocket长连接，能够满足从基础列表到实时Tick数据的全链路需求。
数据覆盖范围
- 市场：KOSPI, KOSDAQ, KONEX
- 品类：股票行情、指数数据、K线、公司基本面、财经新闻
二、准备工作
在开始编码前，需要完成环境准备和权限获取。
1. 获取访问凭证
大多数商业API都需要Key进行鉴权。你需要联系服务商获取API Key（通常称为key）。
注：为了账号安全，请勿在前端代码中硬编码Key，建议在后端进行转发或加密处理。
2. 确认国家标识
在StockTV体系中，通过countryId区分国家。根据文档，韩国的国家ID通常为 11（具体请以官方最新回复为准）。此外，交易所ID（exchangeId）也是常用参数，KRX主板的ID通常为100。
3. API基础信息
Base URL (REST): https://api.stocktv.top
WebSocket URL: wss://ws-api.stocktv.top/connect
三、REST API 核心接口详解
所有接口均返回JSON格式，编码为UTF-8。通用鉴权参数为key。
1. 获取韩国股票列表
这是最基础的接口，用于获取全量或分页的股票池，通常用于初始化本地数据库。
请求示例：
GET /stock/stocks?countryId=11&pageSize=10&page=1&key=YOUR_KEY
关键参数：
countryId: 固定为11（韩国）。exchangeId: 可选，用于区分KOSPI/KOSDAQ。
数据结构亮点：
返回的data.records中包含了丰富的字段，不仅仅是价格，还包括技术指标（如technicalDay日线评级）和基本面数据（如fundamentalMarketCap市值），这对于选股模型非常友好。
{
"symbol": "005930",
"name": "Samsung Electronics Co Ltd",
"last": 0.12,
"chgPct": 0,
"fundamentalMarketCap": 202470000,
"technicalDay": "strong_sell"
}
2. 查询指定股票
如果你知道股票代码（如三星电子的005930），可以通过pid（产品ID）或直接通过symbol进行模糊查询。
GET /stock/queryStocks?symbol=005930&key=YOUR_KEY
3. 获取K线数据（蜡烛图）
K线是量化分析的基础。该接口支持多种时间间隔。
请求示例：
GET /stock/kline?pid=41602&interval=P1D&key=YOUR_KEY
Interval参数对照表：
| 参数值 | 含义 |
|---|---|
| PT5M | 5分钟 |
| PT1H | 1小时 |
| P1D | 日K |
| P1W | 周K |
| P1M | 月K |
注意：time字段为毫秒级时间戳，前端渲染图表时需注意转换。
4. 涨跌排行榜
用于获取市场的极端行情数据，参数type控制榜单类型。
type=1: 涨幅榜type=2: 跌幅榜
四、WebSocket 实时行情对接
对于需要实时报价的应用（如盯盘软件），REST轮询效率太低，必须使用WebSocket。
连接与鉴权
连接地址直接在URL后拼接Key：
wss://ws-api.stocktv.top/connect?key=YOUR_KEY
心跳机制
为了防止连接被服务端断开，客户端需要实现心跳包。一般建议每30秒发送一次Ping消息。
数据解析
服务端推送的数据类型由type字段区分：
type=1: 个股股票数据type=2: 指数数据
实时数据示例解析：
{
"pid": "992844",
"last_numeric": "0.68", // 最新价
"last_dir": "greenBg", // greenBg涨, redBg跌
"pcp": "0.00", // 涨跌幅 (%)
"bid": "0.675", // 买一价
"ask": "0.680", // 卖一价
"timestamp": "1717728251"
}
五、多语言代码示例
为了方便大家快速上手，这里提供Python和JavaScript的核心代码片段。
Python: 获取股票列表与K线
import requests
import pandas as pd
API_KEY = "YOUR_KEY"
BASE_URL = "https://api.stocktv.top"
KOREA_ID = 11
def get_korean_stocks():
params = {
"countryId": KOREA_ID,
"pageSize": 5,
"key": API_KEY
}
response = requests.get(f"{BASE_URL}/stock/stocks", params=params)
if response.status_code == 200:
data = response.json()
for stock in data['data']['records']:
print(f"{stock['symbol']} - {stock['name']}: {stock['last']}")
def get_kline(pid):
params = {
"pid": pid, "interval": "P1D", "key": API_KEY}
res = requests.get(f"{BASE_URL}/stock/kline", params=params)
df = pd.DataFrame(res.json()['data'])
df['time'] = pd.to_datetime(df['time'], unit='ms')
return df
if __name__ == '__main__':
get_korean_stocks()
JavaScript (Node.js/Browser): WebSocket实时行情
const API_KEY = 'YOUR_KEY';
const ws = new WebSocket(`wss://ws-api.stocktv.top/connect?key=${
API_KEY}`);
ws.onopen = () => {
console.log('WebSocket Connected');
// 心跳保活
setInterval(() => {
ws.send(JSON.stringify({
type: 'ping'}));
}, 30000);
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 1) {
// 股票
console.log(`[${
data.pid}] Price: ${
data.last_numeric}, Change: ${
data.pcp}%`);
}
};
ws.onclose = () => {
console.log('Connection closed, retrying...');
// 此处可加入重连逻辑
};
六、避坑指南与最佳实践
在实际开发中，为了保证系统的稳定性，建议关注以下几点：
- 异常处理与重试：网络波动不可避免。建议使用
Retry机制（如Python的urllib3 Retry）处理HTTP 5xx错误或429限流。 - 数据缓存：对于股票列表这类变动不频繁的数据，使用Redis或本地缓存（LRU Cache）存储，减少对API的调用次数。
- 重连策略：WebSocket断开是常态。务必在
onclose事件中实现指数退避算法（Exponential Backoff）进行重连，避免瞬间冲击服务器。 - 时区处理：API返回的时间戳通常是UTC+0的毫秒数，韩国属于UTC+9，展示给用户时记得进行时区转换。
七、总结
通过成熟的第三方API，我们可以低成本地解决韩国股市数据源的问题。本文梳理了从接口鉴权、REST数据拉取、实时流连接到异常处理的全流程。
这套方案不仅适用于韩国市场，通过切换countryId，理论上也可以扩展到东南亚及北美市场，非常适合个人开发者或小团队快速验证产品想法。
