一、背景介绍
先从实际场景说起。假如你需要开发一款面向亚太市场的行情看板，韩国证券交易所（KRX）的数据是必须跨过的门槛。传统爬虫方案？反爬策略日益严格，维护成本急剧上升，更不用说应付频繁变更的接口。最终我们选择了一条更务实的路径——直接使用封装好的金融数据API服务。
本文介绍的接口提供标准的RESTful风格和WebSocket长连接，能够覆盖从基础列表到实时Tick数据的全链路需求。究竟能获取哪些数据？继续往下看。
数据覆盖范围
- 市场：KOSPI、KOSDAQ、KONEX
- 品类：股票行情、指数数据、K线、公司基本面、财经新闻
二、准备工作
动手编码之前，有三件事必须完成：环境准备、权限获取，以及参数确认。先打好基础，再写代码不迟。
1. 获取访问凭证
商业API通常需要Key进行鉴权。你需要联系服务商获取一个API Key（通常称为key）。一句忠告：切勿在前端代码中硬编码Key，建议在后端做转发或加密处理——安全无小事。
2. 确认国家标识
在该体系中，通过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，理论上可以扩展到东南亚甚至北美市场。对于个人开发者或小团队来说，用来快速验证产品想法，再合适不过了。
