韩国市场API技术对接指南，涵盖实时行情、历史数据、指数信息、公司详情等功能

一、概述

StockTV API为开发者提供全面的韩国股票市场数据接口，涵盖实时行情、历史数据、指数信息、公司详情等功能。本指南详细说明如何使用API接口获取韩国市场相关数据，所有接口均返回标准JSON格式。

二、韩国市场特性说明

1. 韩国交易所概览

• 韩国交易所：KRX（Korea Exchange）
• 交易时间：韩国时间 09:00-15:30
• 交易货币：韩元（KRW）
• 涨跌限制：±30%

2. 主要市场板块

• 主板市场（KOSPI）
• 创业板（KOSDAQ）
• 科斯达克（KONEX）

三、接口认证与配置

1. 认证方式

• 所有接口请求需在URL参数中包含API密钥
• 基础认证参数：key=your_api_key_here

2. 基础配置

• 接口地址：https://api.stocktv.top
• 支持协议：HTTPS
• 数据格式：JSON
• 字符编码：UTF-8

四、韩国股票市场接口

1. 股票列表查询

获取韩国市场股票列表，支持分页查询。

接口地址：GET /stock/stocks

请求参数：

参数名	必填	说明	示例值
countryId	是	韩国国家ID为11	11
pageSize	否	每页记录数，默认10	20
page	否	页码，默认1	1
exchangeId	否	交易所ID（60:Seoul, 110:KOSDAQ）	60
key	是	API密钥	your_key

示例请求：

# 获取韩国主板市场股票列表
curl -X GET "https://api.stocktv.top/stock/stocks?countryId=11&pageSize=20&page=1&exchangeId=60&key=your_key"

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 953367,
        "name": "Samsung Electronics",
        "symbol": "005930",
        "last": 84500,
        "chg": 500,
        "chgPct": 0.60,
        "high": 85000,
        "low": 84000,
        "volume": 24567890,
        "avgVolume": 32567890,
        "exchangeId": 60,
        "countryId": 11,
        "countryNameTranslated": "South Korea",
        "flag": "KR",
        "open": true,
        "lastClose": 84000,
        "pairType": "Equities",
        "time": 1755008213,
        "lastPairDecimal": 0
      }
    ],
    "total": 2500,
    "size": 20,
    "current": 1,
    "pages": 125
  }
}

字段说明：

• lastPairDecimal: 价格小数位数（韩国股票通常为整数）
• exchangeId=60: 首尔交易所主板
• exchangeId=110: KOSDAQ创业板

2. 个股详情查询

根据多种条件查询韩国个股详细信息。

接口地址：GET /stock/queryStocks

查询方式示例：

# 通过股票代码查询（三星电子）
curl -X GET "https://api.stocktv.top/stock/queryStocks?symbol=005930&key=your_key"

# 通过PID查询
curl -X GET "https://api.stocktv.top/stock/queryStocks?id=953367&key=your_key"

响应包含韩股特有信息：

{
  "fundamentalBeta": 1.12,
  "fundamentalMarketCap": 450000000000000,  // 市值（韩元）
  "fundamentalRevenue": "302.23T",          // 营收（韩元，T表示万亿）
  "technicalDay": "buy",
  "technicalHour": "neutral",
  "cfd": false                              // 是否差价合约
}

3. 批量股票查询

一次请求获取多个韩国股票的实时数据。

接口地址：GET /stock/stocksByPids

请求示例：

# 查询三星、SK海力士、现代汽车
curl -X GET "https://api.stocktv.top/stock/stocksByPids?pids=953367,953368,953369&key=your_key"

使用场景：

• 自选股监控
• 板块分析
• 投资组合跟踪

4. 韩国股指数据

获取韩国主要股票指数信息。

接口地址：GET /stock/indices

请求参数：

countryId=11&key=your_key

韩国主要指数：

• KOSPI 200
• KOSPI
• KOSDAQ
• KRX 100

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 17950,
      "name": "KOSPI 200",
      "symbol": "KS200",
      "last": 320.45,
      "chg": 2.15,
      "chgPct": 0.68,
      "high": 321.20,
      "low": 318.75,
      "changeDecimalPrecision": 2,
      "changePercentageDecimalPrecision": 2,
      "isOpen": true,
      "flag": "KR",
      "lastPairDecimal": 2,
      "time": 1755008213
    }
  ]
}

5. 通过ID查询指数

获取特定指数的详细信息。

接口地址：GET /stock/indicesById

示例请求：

# 查询KOSPI 200指数
curl -X GET "https://api.stocktv.top/stock/indicesById?id=17950&key=your_key"

6. 历史K线数据

获取韩国股票的历史价格数据。

接口地址：GET /stock/kline

时间周期参数：

interval	说明	韩国适用场景
PT5M	5分钟线	日内高频交易
PT15M	15分钟线	短线交易
PT1H	1小时线	趋势分析
P1D	日线	技术分析主力
P1W	周线	长期投资

示例请求：

# 获取三星电子日K线
curl -X GET "https://api.stocktv.top/stock/kline?pid=953367&interval=P1D&key=your_key"

K线数据格式：

{
  "time": 1754928000000,
  "open": 84000,
  "high": 85000,
  "low": 83500,
  "close": 84500,
  "volume": 24567890,
  "vo": 2075678900000
}

韩股特性注意：

• 价格通常为整数
• 成交额单位较大（韩元）
• 成交量单位：股

7. 韩国IPO信息

获取韩国市场的IPO发行信息。

接口地址：GET /stock/getIpo

请求参数：

countryId=11&type=1&key=your_key

type参数说明：

• 1: 未上市IPO
• 2: 已上市IPO

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 25,
      "ipoListing": 1755008213,
      "country": "South Korea",
      "company": "Kakao Games Corp",
      "exchange": "KOSDAQ",
      "ipoValue": "1.2T",
      "ipoPrice": "32000",
      "last": "34500",
      "symbol": "293490",
      "date": "2025-03-15",
      "pid": 1256789
    }
  ]
}

8. 涨跌排行榜

获取韩国市场的实时涨跌排名。

接口地址：GET /stock/updownList

请求示例：

# 获取韩国涨幅榜
curl -X GET "https://api.stocktv.top/stock/updownList?countryId=11&type=1&key=your_key"

排行榜类型：

type	说明	适用场景
1	涨幅榜	热门股分析
2	跌幅榜	风险监控
3	涨停榜	市场热度
4	跌停榜	风险预警

9. 韩国公司信息

获取韩国上市公司的详细资料。

接口地址：GET /stock/companies

请求示例：

curl -X GET "https://api.stocktv.top/stock/companies?countryId=11&pageSize=10&page=1&key=your_key"

响应示例：

{
  "companyName": "Samsung Electronics Co Ltd Company Profile",
  "description": "Samsung Electronics Co., Ltd. engages in the manufacturing and sale of consumer electronics, IT and mobile communications, and device solutions worldwide...",
  "industry": "Semiconductors",
  "sector": "Technology",
  "employeeCount": 267937,
  "market": "South Korea",
  "countryId": 11
}

10. 通过URL查询公司信息

根据股票详情页URL查询公司信息。

接口地址：GET /stock/companyUrl

韩股URL格式示例：

/equities/samsung-electronics-co-ltd

11. 韩国ETF市场

韩国ETF市场数据查询（需单独开通权限）。

接口特性：

• 韩国是全球重要的ETF市场
• 包含KOSPI 200 ETF、杠杆ETF等
• 支持实时行情和K线数据

五、实时数据推送

1. WebSocket连接

连接地址：

wss://ws-api.stocktv.top/connect?key=your_api_key

JavaScript示例：

// 连接韩国股票WebSocket
const ws = new WebSocket('wss://ws-api.stocktv.top/connect?key=your_key');

ws.onopen = () => {
  console.log('韩国股票WebSocket连接已建立');
  
  // 订阅三星电子
  ws.send(JSON.stringify({
    type: 'subscribe',
    pids: ['953367']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  // 韩股数据处理
  if (data.type === 1) {
    const stockData = {
      pid: data.pid,
      price: parseInt(data.last_numeric),  // 韩元价格通常为整数
      change: parseFloat(data.pc),
      changePercent: parseFloat(data.pcp),
      volume: parseInt(data.turnover_numeric),
      time: data.time
    };
    
    updateStockDisplay(stockData);
  }
};

2. WebSocket数据格式

{
  "pid": "953367",
  "last_numeric": "84500",
  "bid": "84400",
  "ask": "84600",
  "high": "85000",
  "low": "84000",
  "last_close": "84000",
  "pc": "+500",
  "pcp": "+0.60%",
  "turnover_numeric": "24567890",
  "time": "14:30:15",
  "timestamp": "1755008213",
  "type": 1
}

六、韩国市场特殊处理

1. 价格单位处理

// 韩元格式化函数
function formatKRWPrice(price) {
  if (price >= 100000000) {  // 1亿以上
    return Math.floor(price / 100000000) + '억';
  } else if (price >= 10000) {  // 1万以上
    return Math.floor(price / 10000) + '만';
  } else {
    return price.toLocaleString('ko-KR');
  }
}

// 成交额格式化
function formatKRWAmount(amount) {
  if (amount >= 1000000000000) {  // 1조以上
    return (amount / 1000000000000).toFixed(2) + '조';
  } else if (amount >= 100000000) {  // 1억以上
    return (amount / 100000000).toFixed(2) + '억';
  } else {
    return amount.toLocaleString('ko-KR');
  }
}

2. 交易时间处理

// 韩国交易时间判断
function isKoreaTradingTime() {
  const now = new Date();
  const koreaTime = new Date(now.toLocaleString('en-US', { timeZone: 'Asia/Seoul' }));
  const hours = koreaTime.getHours();
  const minutes = koreaTime.getMinutes();
  
  // 韩国时间 09:00-15:30
  if (hours < 9) return false;
  if (hours === 9 && minutes < 0) return false;
  if (hours > 15) return false;
  if (hours === 15 && minutes > 30) return false;
  
  return true;
}

七、数据更新策略

1. 实时性说明

• 股票数据：1-3秒延迟
• 指数数据：5-10秒延迟
• 历史数据：T+1更新
• 韩股休市：周六、周日及韩国公休日

2. 优化建议

class KoreaStockDataManager {
  constructor() {
    this.stockCache = new Map();
    this.lastUpdateTime = {};
    this.cacheDuration = 30000; // 30秒
  }
  
  async getStockData(pid) {
    const now = Date.now();
    const cached = this.stockCache.get(pid);
    
    // 检查缓存有效性
    if (cached && (now - this.lastUpdateTime[pid]) < this.cacheDuration) {
      return cached;
    }
    
    // 重新获取数据
    const data = await this.fetchStockData(pid);
    this.stockCache.set(pid, data);
    this.lastUpdateTime[pid] = now;
    
    return data;
  }
  
  async fetchStockData(pid) {
    const response = await fetch(
      `https://api.stocktv.top/stock/queryStocks?id=${pid}&key=${API_KEY}`
    );
    return response.json();
  }
}

八、应用开发示例

1. 韩股行情展示组件

<div class="korea-stock-widget">
  <div class="stock-header">
    <span class="symbol">005930</span>
    <span class="name">삼성전자</span>
    <span class="market">KOSPI</span>
  </div>
  <div class="stock-price">
    <span class="price">84,500</span>
    <span class="change positive">+500 (+0.60%)</span>
  </div>
  <div class="stock-details">
    <div>고가: 85,000</div>
    <div>저가: 84,000</div>
    <div>거래량: 2,456만주</div>
    <div>거래대금: 2조 756억원</div>
  </div>
</div>

2. 韩股K线图表

// 使用Chart.js绘制韩股K线
async function renderKoreaKLine(pid) {
  const klineData = await fetchKLineData(pid, 'P1D', 30);
  
  const ctx = document.getElementById('korea-chart').getContext('2d');
  const chart = new Chart(ctx, {
    type: 'candlestick',
    data: {
      datasets: [{
        label: '주가',
        data: klineData.map(item => ({
          x: new Date(item.time),
          o: item.open,
          h: item.high,
          l: item.low,
          c: item.close
        }))
      }]
    },
    options: {
      scales: {
        x: { type: 'time' },
        y: {
          ticks: {
            callback: value => value.toLocaleString('ko-KR')
          }
        }
      }
    }
  });
}

3. 实时监控系统

class KoreaStockMonitor {
  constructor() {
    this.ws = null;
    this.subscriptions = new Set();
    this.priceAlerts = new Map();
  }
  
  connect() {
    this.ws = new WebSocket(`wss://ws-api.stocktv.top/connect?key=${API_KEY}`);
    
    this.ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      this.processData(data);
    };
    
    // 断线重连
    this.ws.onclose = () => {
      setTimeout(() => this.connect(), 5000);
    };
  }
  
  subscribe(pid) {
    this.subscriptions.add(pid);
    if (this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({
        type: 'subscribe',
        pids: [pid]
      }));
    }
  }
  
  processData(data) {
    if (data.type !== 1) return;
    
    const price = parseInt(data.last_numeric);
    const pid = data.pid;
    
    // 检查价格预警
    if (this.priceAlerts.has(pid)) {
      const alerts = this.priceAlerts.get(pid);
      alerts.forEach(alert => this.checkAlert(alert, price));
    }
    
    // 更新UI
    this.updateUI(pid, {
      price: price,
      change: data.pc,
      changePercent: data.pcp,
      volume: data.turnover_numeric
    });
  }
}

九、错误处理与监控

1. 错误码处理

const ERROR_CODES = {
  200: '정상 처리되었습니다',
  400: '잘못된 요청 파라미터',
  401: '인증 실패',
  404: '존재하지 않는 종목',
  429: '요청 빈도 초과',
  500: '서버 내부 오류'
};

function handleApiError(code, message) {
  const errorMsg = ERROR_CODES[code] || '알 수 없는 오류';
  console.error(`API 오류 ${code}: ${errorMsg} - ${message}`);
  
  // 使用友好提示
  showUserMessage(`오류가 발생했습니다: ${errorMsg}`);
  
  // 记录日志
  logError({
    code,
    message,
    timestamp: new Date().toISOString()
  });
}

2. 网络异常处理

async function fetchWithRetry(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url);
      if (response.ok) return response;
      
      // 特定状态码重试
      if ([500, 502, 503, 504].includes(response.status)) {
        await delay(1000 * Math.pow(2, i)); // 指数退避
        continue;
      }
      
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === retries - 1) throw error;
      await delay(1000 * Math.pow(2, i));
    }
  }
}

十、性能优化建议

1. 数据缓存策略

class KoreaDataCache {
  constructor() {
    this.cache = new Map();
    this.maxAge = {
      realtime: 3000,    // 3秒
      kline: 60000,     // 1分钟
      company: 3600000  // 1小时
    };
  }
  
  get(key, type = 'realtime') {
    const item = this.cache.get(key);
    if (!item) return null;
    
    const age = Date.now() - item.timestamp;
    if (age > this.maxAge[type]) {
      this.cache.delete(key);
      return null;
    }
    
    return item.data;
  }
  
  set(key, data, type = 'realtime') {
    this.cache.set(key, {
      data,
      timestamp: Date.now(),
      type
    });
  }
}

2. 请求批量化

// 批量查询替代单个查询
async function batchFetchStocks(pids) {
  const batchSize = 50; // 每次最多查询50个
  const results = [];
  
  for (let i = 0; i < pids.length; i += batchSize) {
    const batch = pids.slice(i, i + batchSize);
    const batchResult = await fetch(
      `https://api.stocktv.top/stock/stocksByPids?pids=${batch.join(',')}&key=${API_KEY}`
    );
    results.push(...(await batchResult.json()).data);
  }
  
  return results;
}

十一、合规性注意事项

1. 数据使用规范

• 遵循韩国金融监管要求
• 注明数据来源
• 不得用于非法交易
• 尊重知识产权

2. 用户提示

• 投资有风险提示
• 数据延迟说明
• 免责声明

3. 技术合规

• 遵循GDPR和韩国个人信息保护法
• 实施数据加密
• 定期安全审计

---

本指南详细介绍了StockTV韩国股票市场API的对接方案，涵盖从基础查询到高级应用的各个场景。开发者可根据实际需求选择合适的接口和技术方案，构建稳定、高效的韩股数据应用。建议在实际开发过程中结合具体业务需求，进行适当的性能优化和用户体验改进。