香港株APIで過去のK線データを取得できる？日足・分足・ヒストリカルデータを解説

香港株の相場情報ページを開発する際、最新価格を取得することは通常、最初のステップにすぎません。ユーザーが過去数か月の値動きを確認したり、1分足や5分足に切り替えて取引時間中の価格変動を確認したりできるようにするには、過去のK線データの取得と保存も必要になります。

そのため、香港株APIを選ぶ際には、K線データに対応しているかどうかだけでなく、どの時間足に対応しているか、1回のリクエストで何本取得できるか、指定した日時より前のデータを取得できるかも確認する必要があります。

香港株APIでは過去のK線データを取得できますが、日足と分足ではデータの取得範囲が異なり、1回あたりの取得件数や過去データの取得方法にも明確な制限があります。 特に、数年分の過去データが必要なプロジェクトや、クオンツバックテストを行うプロジェクトでは、開発前にこれらの制限を確認しておくことが重要です。

香港株APIが対応する過去のK線周期

日足と分足は、それぞれ異なる相場分析の用途に適しています。日足は中長期的な値動きの確認や移動平均線などの指標計算に使われます。一方、分足は取引時間中のチャート表示や短期的な分析に適しています。

AllTickの株式K線APIは、以下の周期に対応しています。

香港株は株式データに分類されるため、最短周期は1分足です。2時間足と4時間足には対応していません。また、単一銘柄向けのK線APIでは、1回のリクエストにつき最大500本のデータを取得できます。

実際の開発では、チャートの初期表示に必要な周期に応じて、最初に取得するデータを決めるとよいでしょう。例えば、株式詳細ページでは日足をデフォルトで表示し、ユーザーが分足チャートに切り替えたときに対応する周期のデータをリクエストします。これにより、ページの初期表示時に使用しないデータまで読み込むことを避けられます。

香港株APIで過去のK線データを取得する方法

Tencent Holdingsのコード 700.HK を例に、相場情報ページで直近200本の日足を表示する場合を考えます。この場合、AllTickの株式K線APIを利用できます。

リクエストでは、認証に X-API-Key ヘッダーを使用し、クエリパラメータをAPIパス内の queryData に含めます。Pythonのサンプルコードは以下のとおりです。

import os
import json
import uuid
import requests
from decimal import Decimal
from urllib.parse import quote

api_key = os.environ.get("ALLTICK_API_KEY")

if not api_key:
    raise RuntimeError("Missing ALLTICK_API_KEY")

query_data = {
    "trace": str(uuid.uuid4()),
    "data": {
        "code": "700.HK",
        "kline_type": 8,
        "kline_timestamp_end": 0,
        "query_kline_num": 200,
        "adjust_type": 0
    }
}

base_url = (
    "https://quote.alltick.co/"
    "quote-stock-b-api/v1/kline/"
)

encoded_query = quote(
    json.dumps(query_data, separators=(",", ":")),
    safe=""
)

response = requests.get(
    base_url + encoded_query,
    headers={"X-API-Key": api_key},
    timeout=15
)

response.raise_for_status()
result = response.json()

if result.get("ret") != 200:
    raise RuntimeError(
        f"AllTick API error: {result.get('msg')}"
    )

raw_klines = result.get("data", {}).get("kline_list")

if not isinstance(raw_klines, list):
    raise RuntimeError("Invalid K-line response")

bars = []
seen_timestamps = set()

for item in raw_klines:
    timestamp = int(item["timestamp"])

    if timestamp in seen_timestamps:
        raise RuntimeError(
            f"Duplicate K-line timestamp: {timestamp}"
        )

    seen_timestamps.add(timestamp)

    bars.append({
        "timestamp": timestamp,
        "open": Decimal(item["open_price"]),
        "high": Decimal(item["high_price"]),
        "low": Decimal(item["low_price"]),
        "close": Decimal(item["close_price"]),
        "volume": Decimal(item["volume"]),
        "turnover": Decimal(item["turnover"])
    })

bars.sort(key=lambda item: item["timestamp"])

print(bars)

取得結果に直接影響する主なパラメータは次のとおりです。

• code：銘柄コードを指定します。例の 700.HK はTencent Holdingsに対応します。
• kline_type：K線の周期を指定します。8 は日足、1 は1分足を表します。
• kline_timestamp_end：クエリの終了位置を指定します。0 を設定すると、取得可能な最新の取引周期を起点としてデータを取得します。
• query_kline_num：取得するK線の本数を指定します。1回のリクエストで最大500本まで取得できます。
• adjust_type：株式の調整方式に関するパラメータです。現在のAPIドキュメントに記載されている利用可能な値は 0 です。サポートされていると確認できない値を、利用可能な調整方式として扱わないようにしてください。

レスポンスの kline_list には、タイムスタンプ、始値、高値、安値、終値、出来高、売買代金などのフィールドが含まれます。価格や取引データは文字列として返される場合があるため、このサンプルでは Decimal を使用して数値の精度を維持しています。金融データの計算で二進浮動小数点数を直接使用することによる誤差を避けるためです。

また、このコードではタイムスタンプの重複をチェックし、データを時系列順に並べ替えています。本番環境に接続する際には、銘柄コード、K線周期、タイムスタンプをレコードの複合識別キーとして使用し、データの再同期時に同じレコードが重複して保存されないようにすることもできます。

このコードは、リクエストの構造と基本的なデータ処理ロジックを示すものです。実際のAPI Keyを使用した実行検証は行っていません。

500本のK線で香港株の過去データをどこまで取得できるか

これは、香港株の過去データAPIを評価する際に見落とされやすい制限です。

500本の日足と500本の1分足では、カバーできる期間が大きく異なります。日足は通常、より長い取引期間をカバーしますが、分足は取引時間中にデータポイントが速いペースで蓄積されます。そのため、APIが最大500本を返すからといって、500日分のデータを取得できるとは限りません。また、すべての周期で同じ期間の過去データを取得できるわけでもありません。

さらに、kline_timestamp_end の利用制限にも注意が必要です。AllTickのドキュメントでは、0 を指定すると最新の取引周期を起点にデータを取得できると説明されています。一方、過去のタイムスタンプを終了位置として指定する方法は、株式コードには適用されません。つまり、外国為替や暗号資産向けのタイムスタンプによるページネーションの仕組みをそのまま利用し、終了時刻を繰り返し変更して香港株のより古いK線を取得することはできません。

プランごとのデータ範囲も分けて理解する必要があります。AllTickの総合プランページには、プランごとの一般的な過去K線データの提供期間が記載されていますが、株式データについては直近500本の過去K線が別途明記されています。All HK Stocksの全銘柄向けプランにも、約3,000銘柄を対象とし、直近500本の過去K線を提供すると記載されています。

したがって、プランページに表示された一般的な過去データの提供期間だけを根拠に、特定の香港株のすべての分足周期が同じ年数まで遡れると判断することはできません。実際に取得できるデータ範囲は、銘柄コード、K線周期、契約プランによって確認する必要があります。

数年分の香港株の過去データが必要なプロジェクト、特に長期バックテストや研究に利用する場合は、対象銘柄、必要な周期、取得したい開始日と終了日を事前に明確にし、データが要件を満たすか確認することをおすすめします。APIが株式データの過去タイムスタンプ指定に対応していない場合は、開発完了後にデータ不足が判明することのないよう、別の過去データ取得方法もあらかじめ検討しておく必要があります。

香港株の分足データでリクエストの重複を減らす方法

例えば、ある相場情報プラットフォームで数十銘柄の香港株を同時に表示し、それぞれに日足と1分足のチャートを用意するとします。ユーザーがページを開くたびに、システムが過去K線をすべて再取得すると、APIリクエスト数が増えるだけでなく、すでに保存されているデータも繰り返し転送することになります。

より適切なのは、過去データの初期取得と最新データの更新を分けて処理する方法です。

ここでは、2つのK線関連APIを利用します。

単一銘柄K線API /v1/kline/{queryData}

単一銘柄の過去K線を取得するためのAPIです。1回のリクエストで最大500本を返します。株式詳細ページを開いたときや、ローカルデータベースに対象周期のデータが不足しているときの初期取得に適しています。

バッチK線API /v1/batch-kline

複数の銘柄と複数のK線周期を1回のリクエストで照会できます。ただし、各銘柄の各周期について取得できるのは最新の最大2本です。ローカルデータベースの最新レコードを定期的に更新する用途に適しており、過去K線の取得を代替するものではありません。

また、AllTick WebSocketはK線プッシュに対応していません。アプリケーションでリアルタイムの約定価格、Tickデータ、板情報が必要な場合は、それぞれの用途に対応するAPIを利用する必要があります。リアルタイム相場データのプッシュを、K線のプッシュと同じものとして扱うことはできません。

複数の香港株を同時に監視するシステムでは、必要な過去データを最初に取得してデータベースに保存し、その後、バッチK線APIを使って最新レコードを更新する方法が考えられます。データを書き込む際に銘柄コード、周期、タイムスタンプを使って重複を排除すれば、同じデータの保存を減らせるだけでなく、時系列データの連続性も確認しやすくなります。

香港株の過去K線データの完全性を確認する

APIからデータを取得できたとしても、そのK線データがアプリケーションの要件を満たしているとは限りません。特に分足では、タイムスタンプが連続していないという理由だけで、データ欠損と判断するべきではありません。

香港株市場には、昼休み、週末、祝日、個別銘柄の取引停止など、通常の取引が行われない時間帯があります。こうした時間帯に分足データが存在しなくても、必ずしもデータソースに問題があるとは限りません。

より確実な確認方法は、まず取引カレンダーを用意し、対象銘柄の取引状態とK線周期に基づいて、本来データが存在するはずの時刻を生成することです。本来データがあるべき時間帯に対応するレコードが見つからない場合に、初めてデータ欠損の可能性を詳しく調べます。

あわせて、次の項目も確認することをおすすめします。

• タイムスタンプ：統一された時間基準で保存し、画面に表示するときに香港時間へ変換します。タイムゾーンの処理が一致していないことによるK線の位置ずれを避けるためです。
• 重複レコード：銘柄コード、周期、タイムスタンプを複合識別キーとして使い、同じデータを繰り返し保存しないようにします。
• 価格フィールド：OHLCの数値を正しく解析できるか確認します。また、高値が始値、終値、安値以上であり、安値が始値、終値、高値以下であることなど、基本的な数値関係も確認します。
• 取引フィールド：出来高と売買代金が正しく解析できるか確認します。欠損値を実際の出来高ゼロとして扱わないようにしてください。
• 過去データの範囲：各銘柄について、取得できた最も古いタイムスタンプと最新のタイムスタンプを記録し、APIの返却件数を過去データの完全な取得範囲と混同しないようにします。

香港株の相場情報アプリケーションでは、過去K線はチャート表示だけでなく、指標計算、統計分析、バックテストにも利用される可能性があります。初期段階でタイムスタンプ、重複レコード、取引時間に基づくデータチェックを行うことで、後から発生する問題の調査コストを抑えられます。

多くの香港株コードを接続する必要があるプロジェクト向けに、AllTickは約3,000銘柄をカバーするAll HK Stocksプランを提供しており、直近500本の過去K線やその他の相場データ機能が記載されています。開発者は対象銘柄数、過去データの必要量、リアルタイム更新の頻度を踏まえて、利用が適しているかを判断できます。

香港株のチャート、株式監視ツール、過去相場分析システムを開発している場合は、AllTick香港株相場データ接続ページで接続方法を確認できます。本格的な開発に入る前に、対象銘柄とK線周期を指定して実際に取得できるデータ範囲を確認し、その結果をもとにデータ保存と過去相場データの管理方法を決めることをおすすめします。