StockTV API 对韩国市场的支持非常成熟，覆盖了 KOSPI（主板）和 KOSDAQ（创业板）的实时行情、K 线及指数数据。以下是基于官方文档整理的韩国股票数据对接指南。
一、基础配置与参数说明
在对接前，你需要了解韩国市场的特定参数：
| 参数 Key | 固定值 | 说明 |
|---|---|---|
countryId |
11 | 韩国国家 ID（你指定的参数） |
exchangeId |
60 | 首尔交易所（KOSPI 主板） |
exchangeId |
110 | KOSDAQ 创业板 |
key |
你的密钥 | 必填，需联系 StockTV 获取 |
API 基础信息：
- Base URL:
https://api.stocktv.top - 格式: JSON
- 认证: 所有请求必须在 URL 参数中携带
key
二、核心接口对接代码（PHP）
以下代码封装了韩国股票数据的常用操作，你只需替换 YOUR_API_KEY 即可运行。
<?php
// StockTV API 配置
define('STOCKTV_API_KEY', 'YOUR_API_KEY'); // 请替换为你的实际 Key
define('STOCKTV_BASE_URL', 'https://api.stocktv.top');
/**
* 通用 API 请求函数
*/
function stocktvApiRequest($endpoint, $params = []) {
// 1. 必填参数：Key 和韩国 countryId=11
$defaultParams = [
'key' => STOCKTV_API_KEY,
'countryId' => 11, // 锁定韩国市场
];
$queryParams = array_merge($defaultParams, $params);
$url = STOCKTV_BASE_URL . $endpoint . '?' . http_build_query($queryParams);
// 2. 发起请求（生产环境建议使用 Guzzle 并增加超时/重试逻辑）
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_SSL_VERIFYPEER => false,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
// 3. 解析响应
if ($httpCode === 200) {
return json_decode($response, true);
}
return ['code' => $httpCode, 'message' => 'HTTP Request Failed'];
}
/**
* 1. 获取韩国股票列表（支持分页 & 交易所筛选）
* @param int $page 页码
* @param int $pageSize 每页条数
* @param int|null $exchangeId 60(KOSPI) 或 110(KOSDAQ)
*/
function getKoreaStockList($page = 1, $pageSize = 20, $exchangeId = null) {
$endpoint = '/stock/stocks';
$params = [
'page' => $page,
'pageSize' => $pageSize,
];
// 按交易所筛选（可选）
if ($exchangeId !== null) {
$params['exchangeId'] = $exchangeId;
}
return stocktvApiRequest($endpoint, $params);
}
/**
* 2. 查询个股实时行情（通过 PID 或 Symbol）
* @param int|string $identifier 股票的 PID（推荐） 或 代码（如 '005930'）
*/
function getKoreaStockQuote($identifier) {
$endpoint = '/stock/queryStocks';
$params = [];
// 判断传入的是数字 PID 还是字符串代码
if (is_numeric($identifier)) {
$params['id'] = $identifier; // 使用 PID 查询（更精准）
} else {
$params['symbol'] = $identifier; // 使用股票代码查询
}
return stocktvApiRequest($endpoint, $params);
}
/**
* 3. 获取韩国指数（KOSPI, KOSDAQ 指数）
*/
function getKoreaIndices() {
$endpoint = '/stock/indices';
return stocktvApiRequest($endpoint);
}
/**
* 4. 获取历史 K 线数据
* @param int $pid 股票 PID（从列表接口获取）
* @param string $interval 周期: PT1M, PT5M, PT1H, P1D 等
*/
function getKoreaKline($pid, $interval = 'P1D') {
$endpoint = '/stock/kline';
$params = [
'pid' => $pid,
'interval' => $interval,
];
return stocktvApiRequest($endpoint, $params);
}
// ==================== 使用示例 ====================
// 示例1：获取 KOSPI 主板股票列表（exchangeId=60）
$result = getKoreaStockList(1, 10, 60);
if (isset($result['code']) && $result['code'] == 200) {
$stocks = $result['data']['records'];
foreach ($stocks as $stock) {
echo "代码: {$stock['symbol']}, 名称: {$stock['name']}, 最新价: {$stock['last']}\n";
}
}
// 示例2：查询三星电子（005930）实时行情
$quote = getKoreaStockQuote('005930');
if ($quote['code'] == 200) {
$stockData = $quote['data'];
echo "三星电子: {$stockData['last']} KRW, 涨跌幅: {$stockData['chgPct']}%\n";
}
?>
三、接口返回数据结构参考
1. 股票列表/行情 (/stock/stocks)
返回字段（部分关键字段）：
{
"code": 200,
"data": {
"records": [
{
"id": 953367, // 股票PID（重要，用于查K线）
"symbol": "005930", // 股票代码（三星电子）
"name": "Samsung Electronics",
"last": 84500, // 最新价（韩元，通常为整数）
"chg": 500, // 涨跌额
"chgPct": 0.60, // 涨跌幅（百分比）
"volume": 24567890, // 成交量
"exchangeId": 60, // 交易所ID
"lastPairDecimal": 0 // 价格小数位数（韩股通常为0）
}
]
}
}
2. 实时行情 (/stock/queryStocks)
通过 PID 或 Symbol 查询，返回更详细的实时快照数据（包含买卖盘、基本面等）。
四、韩国市场特性与注意事项
- 交易时间：韩国时间 09:00 - 15:30（UTC+9）。非交易时间接口可能返回闭市价格或无数据 。
- 货币与精度：价格单位为 韩元 (KRW)，绝大多数股票价格是整数，
lastPairDecimal通常为 0。 - 涨跌幅限制：韩国股市单日涨跌幅限制通常为 ±30%。
- PID 的重要性：
id（产品ID）是 StockTV 系统的内部唯一标识，查询 K 线历史数据时必须使用 PID，不能直接使用股票代码。 - 错误处理：务必检查返回 JSON 中的
code字段，200表示成功，非 200 需处理错误信息message。
五、WebSocket 实时推送（可选）
如果你需要毫秒级实时行情（如三星电子股价变动），StockTV 支持 WebSocket 协议。
- 连接地址:
wss://ws-api.stocktv.top/connect?key=YOUR_KEY - 订阅方式: 连接成功后，发送订阅指令（通常包含股票 PID 和动作）即可接收实时 Tick。
第一步：请先申请 API Key（联系 StockTV 官方），将上述代码中的
YOUR_API_KEY替换后即可测试获取韩国股票数据。
