韩国股票 API 对接指南 Seoul&KOSDAQ

一、基础配置

文档明确要求所有 API 请求必须包含 key 参数，您需要先从 StockTV 获取 API Key。

php 复制代码

<?php
// StockTV API 配置
define('STOCKTV_API_KEY', 'YOUR_API_KEY_HERE'); // 从 StockTV 获取
define('STOCKTV_BASE_URL', 'https://api.stocktv.top');
define('KOREA_COUNTRY_ID', 11); // 韩国 countryId

/**
 * 通用 API 请求函数
 */
function stocktvApiRequest($endpoint, $params = []) {
    $params['key'] = STOCKTV_API_KEY; // 必需参数
    
    $url = STOCKTV_BASE_URL . $endpoint . '?' . http_build_query($params);
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    
    $response = curl_exec($ch);
    if ($response === false) {
        return ['error' => 'CURL Error: ' . curl_error($ch)];
    }
    curl_close($ch);
    
    $decoded = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        return ['error' => 'JSON Decode Error'];
    }
    return $decoded;
}
?>

二、韩国股票核心接口

基于文档中的通用接口结构和您提供的 countryId=11，以下是韩国市场的具体实现：

1. 获取韩国股票市场列表

文档中该接口支持分页获取指定国家的股票列表。

php 复制代码

<?php
function getKoreaStockList($page = 1, $pageSize = 50, $exchangeId = null) {
    $endpoint = '/stock/stocks';
    $params = [
        'countryId' => KOREA_COUNTRY_ID, // 韩国
        'page' => $page,
        'pageSize' => $pageSize,
    ];
    
    // 文档提到 exchangeId 是非必要参数，可用于筛选特定交易所
    if ($exchangeId !== null) {
        $params['exchangeId'] = $exchangeId;
    }
    
    return stocktvApiRequest($endpoint, $params);
}

// 使用示例
$result = getKoreaStockList(1, 10);
if (isset($result['code']) && $result['code'] == 200) {
    echo "韩国股票列表 (第1页):\n";
    foreach ($result['data']['records'] as $stock) {
        echo "{$stock['name']} ({$stock['symbol']}): 最新价 {$stock['last']}，涨跌 {$stock['chgPct']}%\n";
    }
}
?>

接口返回字段（根据文档中的示例）：

id: 股票PID，用于后续查询
name / symbol: 股票名称和代码
last / chg / chgPct: 最新价、涨跌额、涨跌幅
high / low / volume: 最高价、最低价、成交量
open: 是否开市
flag: 国家代码（应为"KR"）
countryId: 国家ID（应为11）

2. 韩国交易所说明

从文档中的"市场列表"接口示例可以看到交易所ID的注释：

"exchangeId": 62, //交易所ID 1NYSE 2NASDAQ 54上海交易所 103深圳交易所 46NSE 74BSE 53Mexico 144BIVA 60Seoul 110KOSDAQ 51Toronto 108TSXV 109CSE

其中明确提到了韩国的交易所：

60Seoul: 首尔证券交易所
110KOSDAQ: 韩国科斯达克交易所

因此您可以这样筛选不同交易所的股票：

php 复制代码

<?php
// 获取首尔交易所的股票
function getSeoulExchangeStocks() {
    return getKoreaStockList(1, 50, 60); // exchangeId=60
}

// 获取KOSDAQ的股票
function getKosdaqStocks() {
    return getKoreaStockList(1, 50, 110); // exchangeId=110
}
?>

3. 查询特定韩国股票

php 复制代码

<?php
function queryKoreaStock($pid = null, $symbol = null, $name = null) {
    $endpoint = '/stock/queryStocks';
    $params = [];
    
    if ($pid) $params['id'] = $pid;
    if ($symbol) $params['symbol'] = $symbol;
    if ($name) $params['name'] = $name;
    
    $result = stocktvApiRequest($endpoint, $params);
    
    // 筛选韩国股票
    if (isset($result['code']) && $result['code'] == 200 && is_array($result['data'])) {
        $result['data'] = array_filter($result['data'], function($stock) {
            return ($stock['countryId'] ?? 0) == KOREA_COUNTRY_ID;
        });
    }
    
    return $result;
}
?>

4. 获取韩国股票K线数据

php 复制代码

<?php
function getKoreaStockKline($pid, $interval = 'P1D') {
    $endpoint = '/stock/kline';
    $params = [
        'pid' => $pid,
        'interval' => $interval,
    ];
    return stocktvApiRequest($endpoint, $params);
}

// 使用示例
$klineData = getKoreaStockKline(12345, 'P1D'); // 12345为示例PID
if (isset($klineData['code']) && $klineData['code'] == 200) {
    echo "K线数据获取成功，共" . count($klineData['data']) . "条记录\n";
}
?>

K线时间间隔参数（来自文档）：

PT5M: 5分钟
PT15M: 15分钟
PT1H: 1小时
PT5H: 5小时
P1D: 1天
P1W: 1周
P1M: 1月

5. 获取韩国市场指数

php 复制代码

<?php
function getKoreaIndices() {
    $endpoint = '/stock/indices';
    $params = ['countryId' => KOREA_COUNTRY_ID];
    return stocktvApiRequest($endpoint, $params);
}
?>

预期返回韩国主要指数，如：

KOSPI（韩国综合股价指数）
KOSDAQ指数

6. 获取韩国ETF数据

文档中有一个专门的ETF接口，但需要联系客服开通。您也可以从普通股票接口中筛选ETF：

php 复制代码

<?php
function getKoreaETFs() {
    $endpoint = '/stock/stocks';
    $params = [
        'countryId' => KOREA_COUNTRY_ID,
        'pageSize' => 100,
    ];
    
    $result = stocktvApiRequest($endpoint, $params);
    
    // 筛选ETF（根据pairType或名称包含"ETF"）
    if (isset($result['code']) && $result['code'] == 200 && !empty($result['data']['records'])) {
        $result['data']['records'] = array_filter($result['data']['records'], function($stock) {
            return (isset($stock['pairType']) && $stock['pairType'] === 'ETF') || 
                   (stripos($stock['name'] ?? '', 'ETF') !== false);
        });
    }
    
    return $result;
}
?>

7. 获取韩国IPO新股日历

php 复制代码

<?php
function getKoreaIpo($type = null) {
    $endpoint = '/stock/getIpo';
    $params = ['countryId' => KOREA_COUNTRY_ID];
    
    if (in_array($type, [1, 2])) {
        $params['type'] = $type; // 1=未上市, 2=已上市
    }
    
    return stocktvApiRequest($endpoint, $params);
}
?>

8. 获取韩国股票涨跌排行榜

php 复制代码

<?php
function getKoreaStockRank($type = 1) {
    $endpoint = '/stock/updownList';
    $params = [
        'countryId' => KOREA_COUNTRY_ID,
        'type' => $type, // 1涨幅榜 2跌幅榜 3涨停榜 4跌停榜
    ];
    return stocktvApiRequest($endpoint, $params);
}
?>

三、实时数据推送（WebSocket）

对于实时行情，文档推荐使用WebSocket接口。文档中提供了前端DEMO和Java DEMO链接。

连接地址 : wss://ws-api.stocktv.top/connect?key=您的API_KEY

核心步骤：

建立WebSocket连接
发送订阅消息（包含要订阅的韩国股票PID）
接收实时推送
维持心跳连接

返回数据格式（来自文档示例）：

json 复制代码

{
  "pid": "992844",
  "last_numeric": "0.68",
  "pc": "0.000",
  "pcp": "0.00",
  "volume": "3672800",
  "type": 1
}

四、完整使用示例

php 复制代码

<?php
// 韩国股票数据监控示例
class KoreaStockMonitor {
    
    public function monitorKoreaMarket() {
        // 1. 获取韩国股票列表
        $stocks = getKoreaStockList(1, 20);
        
        // 2. 获取韩国指数
        $indices = getKoreaIndices();
        
        // 3. 获取涨跌榜
        $gainers = getKoreaStockRank(1); // 涨幅榜
        
        // 4. 获取IPO信息
        $ipos = getKoreaIpo(1); // 未上市IPO
        
        return [
            'stocks' => $stocks,
            'indices' => $indices,
            'gainers' => $gainers,
            'ipos' => $ipos
        ];
    }
    
    public function getStockDetail($pid) {
        // 获取股票详细信息
        $stockInfo = queryKoreaStock($pid);
        
        // 获取K线数据
        $kline = getKoreaStockKline($pid, 'P1D');
        
        return [
            'info' => $stockInfo,
            'kline' => $kline
        ];
    }
}
?>

五、重要注意事项

API Key : 所有请求必须包含有效的 key 参数
国家ID : 韩国固定为 countryId=11
交易所ID : 韩国有两个主要交易所
- 首尔交易所: exchangeId=60
- KOSDAQ: exchangeId=110
实时数据: 必须使用WebSocket接口获取实时行情
错误处理 : 检查返回的 code 字段，200 表示成功
数据更新: 韩国股市交易时间为韩国标准时间（UTC+9）

六、韩国股票市场特点

基于模型预训练知识补充：

交易时间: 韩国股市交易时间为平日 09:00-15:30（韩国时间）
货币单位: 韩元（KRW）
主要指数 :
- KOSPI（韩国综合股价指数）
- KOSDAQ（韩国科斯达克指数）
涨跌幅限制: 通常为 ±30%

通过以上接口，您可以全面对接韩国股票的实时行情、历史数据、市场指数等信息。请根据您的实际业务需求组合使用这些接口。