開始使用

玉山行情 WebSocket API 提供台股即時行情服務。透過 WebSocket API 可以滿足您想要接收即時行情的需求。

安裝套件

安裝最新版本的行情 API 套件，請至 SDK 下載頁下載相對應版本。

Python
Node.js

pip install esun_marketdata-<version>-<platform>.whl

目前支援 Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 等版本。

首先先建立一個 project 資料夾，並利用下列指令初始化

npm init

官網下載回來的檔案會像是 esun-marketdata-<version>.tgz，並且把它放入剛剛建立的資料夾中

把 node.js project 裡面的 package.json 增加一行

"dependencies": {
  ...
  "esun-marketdata": "file://<path-to-js-binary>/esun-marketdata-<version>.tgz",
  ...
}

然後到命令行輸入以下指令

npm install

目前支援 Node.js 16 以上版本。

使用 SDK

玉山行情 WebSocket API 提供 Python 與 Node.js SDK。您可以透過以下方式存取 WebSocket API：

並訂閱 WebSocket Callback 方法獲得下方 Callback 訊息。

Python
Node.js

from configparser import ConfigParser
from esun_marketdata import EsunMarketdata

config = ConfigParser()
config.read('/path/to/config.ini')
sdk = EsunMarketdata(config)

sdk.login()

def handle_message(message):
    print(f'message: {message}')

stock = sdk.websocket_client.stock

stock.on("message", handle_message)

stock.connect()

const { EsunMarketdata } = require("@esun/marketdata");

(async () => {
  const sdk = new EsunMarketdata({
    configPath: "/path/to/config.ini",
  });

  await sdk.login();

  const stock = sdk.websocketClient.stock;

  await stock.connect();

  stock.on("message", (message) => {
    const data = JSON.parse(message);
    console.log(data);
  });
})();

身份驗證

當驗證成功後，會收到以下訊息：

{
  "event": "authenticated",
  "data": {
    "message": "Authenticated successfully"
  }
}

若驗證失敗，則收到以下訊息：

{
  "event": "error",
  "data": {
    "message": "Invalid authentication credentials"
  }
}

Heartbeat

每隔 30 秒 WebSocket server 會送出一個 heartbeat 訊息：

{
  "event": "heartbeat",
  "data": {
    "time": "<Timestamp>"
  }
}

Channels

玉山行情 WebSocket API 目前提供以下可訂閱頻道：

訂閱頻道

要訂閱一個頻道可用下方範例進行訂閱：

Python
Node.js

stock.subscribe({
  "channel" : "<CHANNEL_NAME>",
  "symbol" : "<SYMBOL_ID>"
  #"intradayOddLot": True  若要訂閱盤中零股，可再額外加入此參數
})

stock.subscribe({
  channel: "<CHANNEL_NAME>",
  symbol: "<SYMBOL_ID>",
  //intradayOddLot: true  若要訂閱盤中零股，可再額外加入此參數
});

訂閱成功後，會收到以下事件回應：

{
  "event": "subscribed",
  "data": {
    "id": "<CHANNEL_ID>",
    "channel": "<CHANNEL_NAME>",
    "symbol": "<SYMBOL_ID>"
  }
}

支援訂閱同頻道的多檔股票：

Python
Node.js

stock.subscribe({
  "channel" : "<CHANNEL_NAME>",
  "symbols" : ["<SYMBOL_ID>","<SYMBOL_ID>"]
  #"intradayOddLot": True  若要訂閱盤中零股，可再額外加入此參數
})

stock.subscribe({
  channel: "<CHANNEL_NAME>",
  symbols: ["<SYMBOL_ID>", "<SYMBOL_ID>"],
  //intradayOddLot: true  若要訂閱盤中零股，可再額外加入此參數
});

訂閱成功後，會收到以下事件回應：

{
  "event": "subscribed",
  "data": [
    {
      "id": "<CHANNEL_ID>",
      "channel": "<CHANNEL_NAME>",
      "symbol": "<SYMBOL_ID_1>"
    },
    {
      "id": "<CHANNEL_ID>",
      "channel": "<CHANNEL_NAME>",
      "symbol": "<SYMBOL_ID_2>"
    }
  ]
}

訂閱資料回傳

若盤中訂閱成功後，當訂閱標的有新資訊時，會立即透過 data 事件回傳對應資料。

{
  "event": "data",
  "data": {
    ...
  },
  "id": "<CHANNEL_ID>",
  "channel": "<CHANNEL_NAME>"
}

snapshot 事件則是回傳最後一筆快照資料，特別適用於盤後時段，方便開發者們快速了解各頻道的實際資料格式。

{
  "event":"snapshot",
  "data":{
    ...
  },
  "id": "<CHANNEL_ID>",
  "channel": "<CHANNEL_NAME>"
}

取消訂閱

要取消頻道可用下方範例進行取消：

Python
Node.js

stock.unsubscribe({
    'id':'<CHANNEL_ID>'
})

stock.unsubscribe({
  id: "<CHANNEL_ID>",
});

取消訂閱成功後，會收到以下事件回應：

{
  "event": "unsubscribed",
  "data": {
    "id": "<CHANNEL_ID>"
  }
}

支援取消訂閱多個頻道：

Python
Node.js

stock.unsubscribe({
    'ids':['<CHANNEL_ID>','<CHANNEL_ID>']
})

stock.unsubscribe({
  ids: ["<CHANNEL_ID>", "<CHANNEL_ID>"],
});

取消訂閱成功後，會收到以下事件回應：

{
  "event": "unsubscribed",
  "data": [
    {
      "id": "<CHANNEL_ID_1>"
    },
    {
      "id": "<CHANNEL_ID_2>"
    }
  ]
}

安裝套件​

使用 SDK​

身份驗證​

Heartbeat​

Channels​

訂閱頻道​

訂閱資料回傳​

取消訂閱​