POSTPublicfinance-us-shares-ranking

US Stock Rankings

Documentation

API Introduction

This API provides a real-time ranking data query service for the US stock market. Developers can specify sorting fields (e.g., change rate, trading volume, turnover, total market cap) and market categories (all, tech stocks, China concept stocks, etc.) to retrieve list data containing core fields such as stock code, name, real-time price, change, high/low/open/close prices, and market capitalization.

Use Cases

Financial News Applications: Display popular US stock sectors, gainers, or losers lists to enhance user engagement.
Quantitative Trading Assistance: Monitor capital flows and volatility in specific sectors (e.g., tech stocks, China concept stocks).
Investment Research Data Analysis: Track market performance of high-volume or high-market-cap individual stocks to aid investment decisions.

Request and Response Description

Request Method: POST Key Parameters:

sort (Required): Sorting basis, options include changeRate (change rate), volume (trading volume), value (turnover), totalShare (total market capitalization).
market (Required): Market scope, options include all (all), tech (tech stocks), china (China concept stocks), star (star stocks).
asc: Sort order, 0 for descending (default), 1 for ascending.
page / limit: Pagination control, maximum 100 items returned per page.

Response Results: Returns JSON formatted data, where the data.list array contains detailed individual stock information, including fields such as symbol (code), name (name), price (current price), changeRate (change rate), volume (trading volume).

Integration Suggestions

Caching Strategy: Ranking data updates frequently. It is recommended for the frontend to set short-term caching (e.g., 1-5 minutes) to reduce API call frequency.
Error Handling: Please validate the returned code. If the status code is not 200, refer to the msg field for error messages.
Data Display: Note that numeric fields are returned as strings. Frontend display requires formatting amounts and percentages according to business requirements.

Integration Examples

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

Request Example

{
  "sort": "排序字段，可选：changeRate 涨跌率排序，volume 成交量排序，value 成交额排序 ， totalShare 总市值排序",
  "asc": "排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0",
  "page": "页码，默认1",
  "limit": "每页条数，最大100条，默认10",
  "market": "市场代码，可选：all 全部美股 ，tech 科技股，china 中概股，star 明星股"
}

Response Example

{
  "msg": "成功",
  "code": 200,
  "taskNo": "309443174209760778124907",
  "data": {
    "list": [
      {
        "volume": "215748955",
        "symbol": "NVDA",
        "high": "128.2800",
        "low": "121.3600",
        "price": "128.2800",
        "change": "5.61",
        "name": "英伟达",
        "preclose": "122.6700",
        "changeRate": "4.57",
        "value": "27018856766.0000",
        "open": "121.6600",
        "totalShare": "3155475307911"
      }
    ]
  }
}

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 涨跌率排序，volume 成交量排序，value 成交额排序， totalShare 总市值排序
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-us-shares-ranking' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{\n "sort": "排序字段，可选：changeRate 涨跌率排序，volume 成交量排序，value 成交额排序， totalShare 总市值排序",\n "asc": "排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0",\n "page": "页码，默认1",\n "limit": "每页条数，最大100条，默认10",\n "market": "市场代码，可选：all 全部美股，tech 科技股，china 中概股，star 明星股"\n}'

import os import requests url = "https://openapi.toolkk.com/v1/finance-us-shares-ranking" payload = { "sort": "排序字段，可选：changeRate 涨跌率排序，volume 成交量排序，value 成交额排序， totalShare 总市值排序", "asc": "排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0", "page": "页码，默认1", "limit": "每页条数，最大100条，默认10", "market": "市场代码，可选：all 全部美股，tech 科技股，china 中概股，star 明星股" } 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-us-shares-ranking" payload := []byte("{\n \"sort\": \"排序字段，可选：changeRate 涨跌率排序，volume 成交量排序，value 成交额排序， totalShare 总市值排序\",\n \"asc\": \"排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0\",\n \"page\": \"页码，默认1\",\n \"limit\": \"每页条数，最大100条，默认10\",\n \"market\": \"市场代码，可选：all 全部美股，tech 科技股，china 中概股，star 明星股\"\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 涨跌率排序，volume 成交量排序，value 成交额排序， totalShare 总市值排序\",\n \"asc\": \"排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0\",\n \"page\": \"页码，默认1\",\n \"limit\": \"每页条数，最大100条，默认10\",\n \"market\": \"市场代码，可选：all 全部美股，tech 科技股，china 中概股，star 明星股\"\n}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://openapi.toolkk.com/v1/finance-us-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-us-shares-ranking'; $payload = "{\n \"sort\": \"排序字段，可选：changeRate 涨跌率排序，volume 成交量排序，value 成交额排序， totalShare 总市值排序\",\n \"asc\": \"排序顺序，0 倒序（由大到小）， 1正序（由小到大），默认0\",\n \"page\": \"页码，默认1\",\n \"limit\": \"每页条数，最大100条，默认10\",\n \"market\": \"市场代码，可选：all 全部美股，tech 科技股，china 中概股，star 明星股\"\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;

US Stock Rankings

Documentation

API Introduction

Use Cases

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