基于第三方API的韩国KOSPI与KOSDAQ行情数据对接实现指南

一、背景介绍

先从实际场景说起。假如你需要开发一款面向亚太市场的行情看板，韩国证券交易所（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参数对照表：

注意：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，理论上可以扩展到东南亚甚至北美市场。对于个人开发者或小团队来说，用来快速验证产品想法，再合适不过了。