POSTPublicfinance-hk-shares-ranking

Hong Kong Stock Rankings

Documentation

API Introduction

This API provides real-time market ranking services for stocks in the Hong Kong stock market. Developers can obtain a paginated list of stocks by specifying the sorting field (currently only changeRate is supported) and sorting order. The returned data covers key financial and trading indicators such as stock symbol, name, real-time price, change amount, total market capitalization, trading volume, P/E ratio, and 52-week high/low. Data includes a timestamp for tracking update timeliness.

Applicable Scenarios

Financial News Applications: Display Hong Kong stock gainers/losers lists and active stock rankings, providing users with an overview of market hotspots.
Quantitative Trading Assistance: Serve as a preliminary data source for strategy screening, quickly identifying targets with high volatility or specific trends.
Investment Monitoring Dashboards: Integrate into personal or institutional investment dashboards to monitor real-time market anomalies outside of holdings or watchlists.

Request and Response Description

Request Method: POST Core Parameters:

sort (Required): Sorting field, currently only changeRate (change rate) is supported.
asc: Sorting order, 0 for descending (high to low), 1 for ascending (low to high), default is 0.
page: Page number, default is 1.
limit: Number of items per page, maximum 100, default 10.

Response Results:

code/msg: Business status code and description, note the distinction from HTTP status codes.
data.list: Array of stock objects, including symbol (code), name (name), price (current price), changeRate (change rate), market_value (total market capitalization), volume (trading volume), pe (P/E ratio), and other fields.
taskNo: Task order number, used for troubleshooting and service review.

Integration Suggestions

Caching Strategy: Given the high-frequency nature of market data changes, it is recommended that the front end sets a reasonable polling interval (e.g., 3-5 seconds) based on business requirements to avoid resource waste or triggering rate limits due to high-frequency requests.
Error Handling: It is crucial to validate the code field in the response body. Only parse the data content when the code is 200; for non-success statuses, use msg for user prompts or logging.
Data Display: Returned numerical fields (e.g., price, market value) are often in string format. When displaying on the front end, they need to be formatted according to regional customs (e.g., thousands separators, decimal places), and negative values (e.g., EPS or PE for loss-making stocks) should be handled.

Integration Examples

Includes ready-to-use Shell, Python, Go, Java, and PHP examples for direct integration.

Request Example

{
  "sort": "排序字段，目前仅支持：changeRate 涨跌率排序",
  "asc": "排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0",
  "page": "页码，默认1",
  "limit": "每页条数，最大100条，默认10"
}

Response Example

{
  "msg": "成功",
  "code": 200,
  "taskNo": "202960247220113090298671",
  "data": {
    "list": [
      {
        "symbol": "02203",
        "market_value": "75200000.000",
        "change": "0.044",
        "eps": "-0.006",
        "volume": "17180000",
        "shares": "800000000",
        "high": "0.111",
        "update_time": 1713755536,
        "low": "0.064",
        "pe": "-15.6666667",
        "price": "0.094",
        "name": "脑洞科技",
        "ask": "0.094",
        "dividend": "0.000",
        "52week_low": "0.038",
        "preclose": "0.050",
        "bid": "0.091",
        "changeRate": "88.0000000",
        "value": "1586410",
        "open": "0.057",
        "52week_high": "0.210"
      }
    ]
  }
}

Request Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
type	string	object
properties	object	{...}
properties.sort	object	{...}
properties.sort.type	string	string
properties.sort.description	string	排序字段，目前仅支持：changeRate 涨跌率排序
properties.asc	object	{...}
properties.asc.type	string

Response Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
type	string	object
properties	object	{...}
properties.msg	object	{...}
properties.msg.type	string	string
properties.msg.example	string	成功
properties.msg.description	string	接口返回码对应的描述信息
properties.code	object	{...}

curl --request POST \ --url 'https://openapi.toolkk.com/v1/finance-hk-shares-ranking' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{\n "sort": "排序字段，目前仅支持：changeRate 涨跌率排序",\n "asc": "排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0",\n "page": "页码，默认1",\n "limit": "每页条数，最大100条，默认10"\n}'

import os import requests url = "https://openapi.toolkk.com/v1/finance-hk-shares-ranking" payload = { "sort": "排序字段，目前仅支持：changeRate 涨跌率排序", "asc": "排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0", "page": "页码，默认1", "limit": "每页条数，最大100条，默认10" } headers = { "Content-Type": "application/json", "X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"), } response = requests.request("POST", url, headers=headers, json=payload, timeout=30) response.raise_for_status() print(response.json())

package main import ( "bytes" "fmt" "io" "net/http" ) func main() { endpoint := "https://openapi.toolkk.com/v1/finance-hk-shares-ranking" payload := []byte("{\n \"sort\": \"排序字段，目前仅支持：changeRate 涨跌率排序\",\n \"asc\": \"排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0\",\n \"page\": \"页码，默认1\",\n \"limit\": \"每页条数，最大100条，默认10\"\n}") req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload)) if err != nil { panic(err) } req.Header.Set("Content-Type", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println(string(body)) }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class ToolkkExample { public static void main(String[] args) throws Exception { String payload = "{\n \"sort\": \"排序字段，目前仅支持：changeRate 涨跌率排序\",\n \"asc\": \"排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0\",\n \"page\": \"页码，默认1\",\n \"limit\": \"每页条数，最大100条，默认10\"\n}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://openapi.toolkk.com/v1/finance-hk-shares-ranking")) .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .header("Content-Type", "application/json") .header("X-API-Key", "YOUR_API_KEY") .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }

<?php $endpoint = 'https://openapi.toolkk.com/v1/finance-hk-shares-ranking'; $payload = "{\n \"sort\": \"排序字段，目前仅支持：changeRate 涨跌率排序\",\n \"asc\": \"排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0\",\n \"page\": \"页码，默认1\",\n \"limit\": \"每页条数，最大100条，默认10\"\n}"; $ch = curl_init($endpoint); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'X-API-Key: YOUR_API_KEY', ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); if ($response === false) { throw new RuntimeException(curl_error($ch)); } curl_close($ch); echo $response;

Hong Kong Stock Rankings

Documentation

API Introduction

Applicable Scenarios

Request and Response Description

Integration Suggestions

Integration Examples

Request Example

Response Example

Request Fields

Response Fields

Shell Example

Python Example

Go Example

Java Example

PHP Example

Try it online