ptrade 平台 get_gear_price 档位行情数据结构与解析方法

get_gear_price 返回数据结构详解

在 ptrade 量化交易平台中，get_gear_price(sids) 函数用于获取指定代码的档位行情价格。其返回的数据结构是一个嵌套的字典（dict），主要包含委买档位和委卖档位信息。

1. 核心字段说明

返回的字典主要包含两个核心字段：

• bid_grp: 委买档位数据。
• offer_grp: 委卖档位数据。

这两个字段的值也是字典，其键（Key）为档位级别（如 1 代表买一/卖一，2 代表买二/卖二等），值（Value）为一个列表（List），包含该档位的具体信息。

列表中的元素依次为：

1. 价格 (float): 该档位的委托价格。
2. 委托量 (int): 该档位的总委托数量。
3. 委托笔数 (int): 该档位的总委托笔数（若无 L2 行情，此字段返回 0）。
4. 委托队列 (dict, 可选): 仅在 L2 行情下的第一档（买一/卖一）可能包含此数据，展示前 50 笔具体的委托明细（如 {1: 33200, 2: 104800, ...}）。

2. 数据结构示例

根据传入参数的不同（单只代码 vs 多只代码），返回的结构略有差异。

单只代码返回结构

直接返回包含 bid_grp 和 offer_grp 的字典：

{
    'bid_grp': {
        1: [13.68, 15225900, 4905], 
        2: [13.67, 30200, 32], 
        # ... 更多档位
    },
    'offer_grp': {
        1: [13.69, 50000, 10], 
        2: [13.70, 20000, 5], 
        # ... 更多档位
    }
}

多只代码返回结构

返回以股票代码为键的嵌套字典：

{
    '600570.SS': {
        'bid_grp': {1: [41.88, 1200, 0], 2: [41.87, 2300, 0], ...},
        'offer_grp': {1: [41.89, 4400, 0], 2: [41.90, 13020, 0], ...}
    },
    '000001.SZ': {
        'bid_grp': {1: [15.01, 5000, 0], ...},
        'offer_grp': {1: [15.02, 6000, 0], ...}
    }
}

涨停股/L2行情特殊结构

对于涨停股或开通 L2 行情的情况，第一档数据可能会包含委托队列，且卖盘可能为空：

{
    'bid_grp': {
        1: [13.68, 15225900, 4905, {1: 33200, 2: 104800, 3: 1000, 4: 100, 5: 51800}], # 包含委托队列
        2: [13.67, 30200, 32], 
        # ...
    }, 
    'offer_grp': {
        1: [0.0, 0, 0, {}], # 涨停时卖一为空
        2: [0.0, 0, 0], 
        # ...
    }
}

3. 如何解析档位数据

以下是一个在 handle_data 中获取并解析 get_gear_price 数据的代码示例：

def initialize(context):
    g.security = '600570.SS'
    set_universe(g.security)

def handle_data(context, data):
    # 获取单只股票的档位行情
    gear_data = get_gear_price(g.security)
    
    # 检查是否获取成功（失败时返回 {'bid_grp': {}, 'offer_grp': {}}）
    if not gear_data.get('bid_grp'):
        log.warning(f"获取 {g.security} 档位数据失败或为空")
        return
        
    # 解析买一档数据
    buy_1_info = gear_data['bid_grp'].get(1)
    if buy_1_info:
        buy_1_price = buy_1_info[0]   # 买一价
        buy_1_vol = buy_1_info[1]     # 买一量
        buy_1_count = buy_1_info[2]   # 买一笔数
        log.info(f"买一价: {buy_1_price}, 买一量: {buy_1_vol}, 买一笔数: {buy_1_count}")
        
        # 检查是否包含 L2 委托队列 (列表长度大于3)
        if len(buy_1_info) > 3:
            buy_1_queue = buy_1_info[3]
            log.info(f"买一委托队列: {buy_1_queue}")

    # 解析卖一档数据
    sell_1_info = gear_data['offer_grp'].get(1)
    if sell_1_info:
        sell_1_price = sell_1_info[0]
        log.info(f"卖一价: {sell_1_price}")

注意事项

1. 异常处理：获取实时行情快照失败时，返回的档位内容为空字典 {"bid_grp": {}, "offer_grp": {}}，解析前务必进行判空处理。
2. L2 权限：委托笔数和第一档的委托队列数据依赖于券商是否开通了 Level-2 行情，若未开通，委托笔数通常返回 0，且无委托队列字典。