沪深港股历史行情接口能查到什么：K线周期、复权与返回字段

要画一张历史 K 线图，开发者常卡在三件事上：周期参数怎么取、复权方式什么时候生效、返回数组里的每个字段对应什么含义。本文围绕沪深港股历史行情接口，把这四个查询参数、返回结构、错误码与使用边界逐项拆开，并给出四种语言的可运行调用示例。全文按「能查到什么 → 怎么构造请求 → 怎么读返回」组织，适合做技术分析、图表渲染或教学演示时对照查阅。

一、沪深港股历史行情接口技术简介

沪深港股历史行情接口是一个返回证券历史 K 线序列的查询接口。调用方传入股票代码，并可指定 K 线周期、起始日期与复权方式；接口以 GET 方式返回 JSON 数据，主体是一组按时间倒序排列的 K 线记录。每条记录包含时间点、区间开始价、区间结束价、区间最低价、区间最高价与区间成交手数，外层同时带回证券代码、名称、市场标识与记录条数。

从数据用途看，这组字段可以直接喂给蜡烛图、折线图或均线计算逻辑，也可以作为技术指标计算的输入。接口覆盖沪深两市与港股代码段，港股在周期支持上与沪深存在差异。商品页明确标注：本接口数据仅用于学习分析，不得用于对外展示。这一点决定了它的接入方式应围绕本地分析与内部工具展开，而不是面向终端用户的行情页面。

二、沪深港股历史行情接口能力概览

下表按维度列出接口提供的能力，均为中性技术描述。

「能查到什么」可以概括为一句话：给定代码与时间起点，拿到一段按周期聚合的价量序列。它不返回实时盘口、逐笔成交、财务指标或技术指标计算结果，后者需要另行计算或接入其他数据源。

三、沪深港股历史行情接口适用场景

以下只描述技术情境与数据流向，不涉及业务收益判断。

场景的共同点是：接口只负责提供原始 K 线数组，聚合、绘图、指标与存储都在调用方一侧完成。把边界划清楚，接入时的参数设计与异常处理会更有针对性。

四、沪深港股历史行情接口接入流程

4.1 请求参数表

接口为 GET 请求，Query 参数共四个，Header 与 Body 均无额外参数。

4.2 标准接入步骤

1. 在控制台获取接入地址与 AppCode，凭据只保存在服务端配置中。
2. 构造 GET 请求，把四个参数按上表拼进 Query。
3. 在请求头写入 Authorization: APPCODE <appcode>。
4. 设置连接与读取超时，发起请求并读取 HTTP 状态码。
5. 状态码为 200 时解析响应正文，先判断业务码，再读取 K 线数组。
6. 按周期把时间字段解析为对应粒度，映射到内部数据结构。

参数设计上容易忽略两处：beginDay 只控制起点，结束点由接口固定为当前时间；type 在分钟周期下传入也不会生效。这两点若未显式处理，容易在回测中出现「参数传了但结果没变」的困惑。

五、沪深港股历史行情接口调用示例与返回结构

5.1 请求构造（四种语言）

示例统一用 HOST 表示控制台给出的接入地址，用 APPCODE 表示凭据；正文中不写死任何域名。请求路径为 /realtime-k。

Java

import java.util.HashMap;
import java.util.Map;

public class KlineDemo {
   
    public static void main(String[] args) {
   
        String host = HOST;                 // 控制台给出的接入地址
        String path = "/realtime-k";
        String appcode = APPCODE;

        Map<String, String> headers = new HashMap<>();
        headers.put("Authorization", "APPCODE " + appcode);

        Map<String, String> querys = new HashMap<>();
        querys.put("code", "600004");
        querys.put("time", "day");
        querys.put("beginDay", "20190801");
        querys.put("type", "bfq");

        // 使用项目内已有的 HTTP 工具发起 GET，并设置连接/读取超时
        // HttpResponse response = HttpUtils.doGet(host, path, "GET", headers, querys);
        // System.out.println(response.toString());
    }
}

PHP

<?php
$host    = HOST;          // 控制台给出的接入地址
$appcode = APPCODE;
$params  = [
    'code'     => '600004',
    'time'     => 'day',
    'beginDay' => '20190801',
    'type'     => 'bfq',
];
$url = $host . '/realtime-k?' . http_build_query($params);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $url,
    CURLOPT_HTTPHEADER     => ['Authorization: APPCODE ' . $appcode],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code === 200) {
   
    $json = json_decode($body, true);
    print_r($json['res_body']['dataList'] ?? []);
}

Python

import requests

HOST = "控制台给出的接入地址"
APPCODE = "你的 AppCode"

resp = requests.get(
    HOST + "/realtime-k",
    headers={
   "Authorization": "APPCODE " + APPCODE},
    params={
   
        "code": "600004",
        "time": "day",
        "beginDay": "20190801",
        "type": "bfq",
    },
    timeout=10,
)
resp.raise_for_status()
payload = resp.json()
if payload.get("res_code") == 0:
    for item in payload["res_body"]["dataList"]:
        print(item["time"], item["open"], item["close"], item["min"], item["max"], item["volumn"])

JavaScript（Node.js）

const HOST = "控制台给出的接入地址";
const APPCODE = "你的 AppCode";

const qs = new URLSearchParams({
   
  code: "600004",
  time: "day",
  beginDay: "20190801",
  type: "bfq",
});

const res = await fetch(`${
     HOST}/realtime-k?${
     qs}`, {
   
  headers: {
    Authorization: `APPCODE ${
     APPCODE}` },
  signal: AbortSignal.timeout(10000),
});
if (!res.ok) throw new Error(`HTTP ${
     res.status}`);
const payload = await res.json();
if (payload.res_code === 0) {
   
  console.table(payload.res_body.dataList);
}

5.2 返回结构样例

为便于阅读，外层字段以通用名称示意；实际字段命名以控制台返回的响应为准。数组按时间倒序排列，示例中仅保留两条记录。

{
   
  "res_code": 0,
  "res_error": "",
  "res_body": {
   
    "code": "600004",
    "name": "示例证券",
    "market": "sh",
    "count": "8",
    "ret_code": 0,
    "dataList": [
      {
   
        "time": "20161110",
        "open": "14.910",
        "close": "15.170",
        "min": "14.910",
        "max": "15.320",
        "volumn": "53486.000"
      },
      {
   
        "time": "20161109",
        "open": "15.040",
        "close": "14.830",
        "min": "14.680",
        "max": "15.070",
        "volumn": "57193.000"
      }
    ]
  }
}

5.3 返回字段说明

所有价量字段都是字符串，直接做数值比较会得到字典序结果。建议在解析层统一转成浮点并保留三位小数，再交给图表组件；time 则按 time 参数的取值选择 yyyyMMddHHmm 或 yyyyMMdd 解析格式。

六、沪深港股历史行情接口在线调试实录

以 code=600004、time=day、beginDay=20190801、type=bfq 为例走查一次完整调试。

步骤 1：在调试面板填入四个 Query 参数，Header 只保留 Authorization。

步骤 2：发起请求，观察 HTTP 状态码为 200，响应体为 JSON。

步骤 3：先读外层业务码，为 0 后进入主体，确认 code 与请求一致、market 为 sh、count 与实际数组长度一致。

步骤 4：展开 dataList，第一条 time 为最近的交易日，后续按时间倒序；四值字段均为带三位小数的字符串。

步骤 5：把 time 改成 week，再次发起请求，数组粒度变为周；把 type 改成 qfq，对比同一时间点的四值差异。

周期与时间粒度的对应关系如下，港股一列单独标出：

复权只在日/周/月周期生效，三种取值的差别在于除权除息日的序列如何对齐：

调试时若返回空数组，优先核对 code 是否为有效代码、beginDay 是否为交易日或更早的日期，再看该代码在所选市场是否存在对应的周期数据，不要直接把空数组当成接口异常。

七、沪深港股历史行情接口调用限制与规范

以下为事实性描述，具体数值以控制台实时配置为准。

工程实践上建议补四件事：参数前置校验（代码格式、yyyyMMdd 合法性、周期与市场的组合）、带退避的失败重试（仅对 500 与网络超时）、结果缓存（同一组参数短期内复用）、调用日志脱敏（不记录完整凭据）。这些处理都在调用方一侧，不改变接口本身的返回结构。

八、沪深港股历史行情接口能力边界与免责声明

把「支持 / 不支持 / 边界」写成清单，比在代码里散落判断更好维护：接入层可以先按清单做一次参数组合校验，把不支持的组合在进入网络请求之前就拦截掉。

九、沪深港股历史行情接口错误码与排查指南

排查顺序建议固定为：先看 HTTP 状态码 → 再看业务码 → 最后看数组是否为空。403/500/555 三类问题的处理动作完全不同，混在一起判断容易把「参数错」误当成「额度不足」。

十、沪深港股历史行情接口常见问题 FAQ

问：这个接口能查到哪些字段，能直接画 K 线图吗？
能查到时间点、区间开始价、区间结束价、区间最低价、区间最高价与成交手数，加上代码、名称、市场标识与条数。四值字段加时间字段即可画蜡烛图，但需要把字符串数值转成浮点。

问：beginDay 能不能同时限定结束日期？
不能。beginDay 只指定起点，结束时间固定为当前时间。需要固定终点时，在本地按日期裁剪数组。

问：港股为什么传 time=5 没有分钟数据？
港股不支持 5 分、30 分、60 分 K，只支持 day、week、month。接入层应对「港股 + 分钟周期」做前置拦截或自动降级到 day。

问：type=qfq 在分钟周期下有效吗？
无效。复权取值仅在 time 为 day、week、month 时生效，分钟周期下传入不参与计算。

问：一次能查多只股票吗？
单次请求只接受一个 code。需要批量时由调用方遍历代码清单，并自行控制并发与调用量。

问：返回数据可以在产品页面上对外展示吗？
不可以。商品页明确标注数据仅用于学习分析，不得用于对外展示，接入时应把使用范围限制在本地分析与内部工具。

十一、内容小结

沪深港股历史行情接口的作用可以归纳为：按代码与起始日期，返回一段按周期聚合的价量序列，用于本地图表渲染、指标练习与内部分析。本文给出的关键点有四处：

1. 四个参数中，code 必填，time 决定周期与时间字段精度，beginDay 只控制起点，type 只在日/周/月周期生效。
2. 返回结构是「外层业务码 → 主体元信息 → dataList 数组」三层，价量与条数均为字符串，解析层需要统一转型。
3. 港股仅支持日/周/月周期；数组按时间倒序；结束时间固定为当前时间。
4. 403、500、555 分别对应调用量、网关内部、传参三类问题，排查时按「状态码 → 业务码 → 空数组」顺序进行。

接入前请再确认两件事：控制台给出的接入地址与凭据配置，以及数据仅用于学习分析、不得用于对外展示的使用边界。参数组合的合法性校验、超时重试与结果缓存都放在调用方一侧实现，接口本身只返回原始 K 线数组。