调用价格
5 匠币/次
快速接入
保持统一返回结构,直接通过服务端发起请求即可接入。
https://openapi.toolkk.com/v1/finance-us-shares-rankingcURL 示例
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}'Python 示例
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())Go 示例
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))
}Java 示例
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 示例
<?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;响应示例
{
"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"
}
]
}
}示例用于理解返回结构,实际结果以接口返回为准。
- 鉴权方式
- 请求头传入 X-API-Key
- 默认限流
- 60 次/分钟
- 超时时间
- 5000 ms
服务端调用时,将 API Key 放在 X-API-Key 请求头中。
建议按 response code 与业务字段双重判断调用结果。
高频调用场景请结合速率限制与重试策略使用。
请求字段
从服务端发起请求,并在 X-API-Key 请求头中传入密钥。
请求字段
字段来自接口结构定义。未提供的说明和示例会标为未标注。
| 字段路径 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| sort | string | 是 | 排序字段,可选:changeRate 涨跌率排序,volume 成交量排序,value 成交额排序 , totalShare 总市值排序 | 未标注 |
| asc | string | 否 | 排序顺序,0 倒序(由大到小), 1正序(由小到大),默认0 | 未标注 |
| page | string | 否 | 页码,默认1 | 未标注 |
| limit | string | 否 | 每页条数,最大100条,默认10 | 未标注 |
| market | string | 是 | 市场代码,可选:all 全部美股 ,tech 科技股,china 中概股,star 明星股 | 未标注 |
请求示例
{
"sort": "排序字段,可选:changeRate 涨跌率排序,volume 成交量排序,value 成交额排序 , totalShare 总市值排序",
"asc": "排序顺序,0 倒序(由大到小), 1正序(由小到大),默认0",
"page": "页码,默认1",
"limit": "每页条数,最大100条,默认10",
"market": "市场代码,可选:all 全部美股 ,tech 科技股,china 中概股,star 明星股"
}- 鉴权方式
- 请求头传入 X-API-Key
- 默认限流
- 60 次/分钟
- 超时时间
- 5000 ms
响应字段
示例用于理解返回结构,实际结果以接口返回为准。
响应字段
字段来自接口结构定义。未提供的说明和示例会标为未标注。
| 字段路径 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| msg | string | 否 | 返回码对应描述 | 成功 |
| code | number | 否 | 返回码,详见返回码说明 | 200 |
| taskNo | string | 否 | 本次请求号 | 309443174209760778124907 |
| data | object | 否 | 未标注 | 未标注 |
| data.list | array | 否 | 未标注 | [{"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"}] |
| data.list[] | object | 未标注 | 未标注 | 未标注 |
响应示例
{
"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"
}
]
}
}接口简介
接口能力、应用场景、使用限制与常见问题。
接口能力
按市场分类和指定指标查询美股排序列表。公开分类包含全部美股、科技股、中概股和明星股;可按涨跌率、成交量、成交额或总市值排序,并控制升降序与分页。每页默认10条,最多100条,结果含代码、名称、价格及相关行情数值。它提供查询时返回的候选记录,完整分类成员、行情时间和市场覆盖没有保证,不能据此认定全市场实时榜单。
应用场景
行情看板可按涨跌率升降序展示不同方向的榜单;资料浏览可选择科技股或中概股分类并翻页,选中代码后进入调用方自己的详情页面;监控任务可保存相同查询条件的列表快照,比较新增或名次变化供研究。快照对比、提醒、财务分析和交易判断需调用方实现,榜单排名本身不代表股票质量、流动性保证或未来表现。
从输入到结果
选择必需的市场分类和排序指标,按需设置页码、条数与方向,输入均按公开字符串格式提交。方向0为由大到小且默认,1为由小到大;页码默认1。检查调用状态后遍历 data.list,保存证券代码与查询条件。行情数值为字符串,计算或重新排序前应检查空值并按十进制解析,不能按字符串字典顺序比较。总市值排序使用 totalShare,不能仅按字段名当作股份数量。
范围与限制
当前响应没有报价时间、币种、延迟状态、交易所或分页总条数。涨跌率数值单位与价格计量口径未展开,展示时先保留原值,不自行补百分号或统一换算。分类的纳入规则、盘前盘后范围和翻页期间的稳定性未说明,跨页记录需自行核对重复与变化。空列表不能直接认定某类股票不存在或已经遍历完整市场;重要行情解释需另行确认时点和口径。
常见问题
可以按交易所分别筛选吗?
当前只公开四类市场选项,没有交易所筛选字段。不能把科技股或明星股分类等同于某个交易所清单。
总市值字段是不是总股数?
排序说明把totalShare用于总市值排序,应按该说明理解;具体计量单位没有展开,不应直接显示为股份数量。
涨跌率字符串可以直接加百分号吗?
公开定义未明确数值单位,先保留原值并确认口径。计算前做数值与空值检查,不从网页展示推导API单位。
空页是不是已经到最后一页?
响应没有总条数或末页标志。先核对分类、排序和页码,再处理实际空结果,不能仅凭空页保证已经取得全部记录。