怎么用越南行情数据API接口获取涨幅榜
行情网站的首页通常都有一块「今日涨幅榜」：哪些股票涨得最多、哪些跌得最多、哪些成交最活跃。这篇教学方案用我们的越南行情数据API接口，一次请求取到越南股票的涨幅榜，再用同样的写法取跌幅榜和活跃榜，文末有可以直接运行的完整代码。
榜单里有什么
三个榜单各是一个接口，参数相同，每个榜单按名次返回 20 条：
gainer_list：涨幅榜，涨幅最大的股票loser_list：跌幅榜，跌幅最大的股票active_list：活跃榜，成交最活跃的股票
每一条里有产品代码、名称、所在交易所、价格、涨跌幅、成交量和板块。
准备工作
- 一把密钥。能用哪些国家和接口是开通账号时确定的，申请时说明要用越南的财务信息接口。
- 接入地址。HTTP 的接入地址写在开发文档的通用规则里，下文用「HTTP 接入地址」代替。
- 国家参数：
country=vietnam。其它国家的取值见国家与市场参数。
第一步：请求涨幅榜
用到的接口是活跃榜、涨幅榜、跌幅榜。请求头带 Authorization: 你的密钥，只有一个参数：
GET /api/gainer_list?country=vietnam返回（data 里共 20 条，这里只列出前 2 条）：
{
"status": 0,
"message": "SUCCESS",
"data": [
{
"market": "vietnam",
"volume": "28.54 K",
"country": "vietnam",
"symbol": "HKB",
"original": "UPCOM:HKB",
"price": "400 VND",
"change": "+33.33%",
"name": "Ha Noi - Kinh Bac Agriculture and Food Joint Stock Company",
"exchange": "UPCOM",
"type": "GAINER",
"sector": "Công nghiệp chế biến"
},
{
"market": "vietnam",
"volume": "610",
"country": "vietnam",
"symbol": "LO5",
"original": "UPCOM:LO5",
"price": "400 VND",
"change": "+33.33%",
"name": "Lilama 5 JSC",
"exchange": "UPCOM",
"type": "GAINER",
"sector": "Dịch vụ công nghiệp"
}
],
"total": 0,
"page": 0,
"market": null,
"symbol": null,
"code": null,
"interval": null
}数据在 data 里，已经按名次排好，status 为 0 表示成功。original 是「交易所:代码」的写法，exchange 是所在的交易所，越南有 HOSE、HNX、UPCOM 三个市场。
第二步：把文本转成数字
榜单里的价格、涨跌幅、成交量都是给人看的文本，直接显示没有问题，要排序或者计算就得先转成数字：
price带币种，如"400 VND"；大的数带千位分隔的逗号，如"798,000 VND"。change带正负号和百分号，如"+33.33%"。下跌用的负号是−（U+2212），不是键盘上的减号-，直接转数字会失败，要先换掉。volume带单位，如"28.54 K"（千）、"1.09 M"（百万），量小的时候没有单位，如"610"。sector是板块名称，越南用的是越南文，也可能是null，显示之前先判断一下。
完整示例代码里有这三个转换函数，可以直接拿去用。
第三步：跌幅榜和活跃榜
换一个接口名就行，参数不变：
GET /api/loser_list?country=vietnam
GET /api/active_list?country=vietnam返回的写法和涨幅榜相同，只有 type 不一样：涨幅榜是 GAINER，跌幅榜是 LOSER，活跃榜是 ACTIVE。
完整示例代码
下面的代码用 Node.js 18 及以上版本可以直接运行（自带 fetch），把开头两项换成自己的即可。
// 运行：node rank.js（Node.js 18 及以上）
const KEY = '你的密钥';
const HTTP_BASE = 'HTTP 接入地址'; // 见开发文档「概览 · 通用规则」，以 /api/ 结尾
// "+33.33%"、"−40.00%" → 33.33、-40（下跌用的负号是 U+2212，先换成普通减号）
const toPercent = (s) => Number(s.replace('−', '-').replace('%', ''));
// "798,000 VND" → { value: 798000, currency: 'VND' }
const toPrice = (s) => { const [v, currency] = s.split(' '); return { value: Number(v.replace(/,/g, '')), currency }; };
// "28.54 K"、"1.09 M"、"610" → 28540、1090000、610；遇到没见过的单位得到 NaN
const toVolume = (s) => { const [v, unit = ''] = s.split(' '); return Math.round(Number(v) * { '': 1, K: 1e3, M: 1e6 }[unit]); };
// name 写 gainer_list（涨幅榜）、loser_list（跌幅榜）或 active_list（活跃榜）
async function rank(name, country) {
const res = await fetch(`${HTTP_BASE}${name}?${new URLSearchParams({ country })}`, { headers: { Authorization: KEY } });
const text = await res.text();
const body = JSON.parse(text);
if (body.status !== 0) throw new Error(`取不到 ${country} 的 ${name}：${body.message || text}`);
return body.data.map((x) => ({
code: x.original, name: x.name, sector: x.sector || '—',
price: toPrice(x.price), percent: toPercent(x.change), volume: toVolume(x.volume),
}));
}
async function main() {
for (const [name, title] of [['gainer_list', '涨幅榜'], ['loser_list', '跌幅榜'], ['active_list', '活跃榜']]) {
const list = await rank(name, 'vietnam');
console.log(`${title}（共 ${list.length} 条）前 3 名：`);
list.slice(0, 3).forEach((x, i) => console.log(` ${i + 1}. ${x.code} ${x.price.value} ${x.price.currency} ${x.percent}% 成交量 ${x.volume}`));
}
}
main().catch((e) => console.error(e.message));运行后的输出：
涨幅榜（共 20 条）前 3 名：
1. UPCOM:HKB 400 VND 33.33% 成交量 28540
2. UPCOM:LO5 400 VND 33.33% 成交量 610
3. UPCOM:FTM 500 VND 25% 成交量 188600
跌幅榜（共 20 条）前 3 名：
1. UPCOM:ACM 300 VND -40% 成交量 1090000
2. UPCOM:PTM 7600 VND -26.92% 成交量 2300
3. UPCOM:VAF 22600 VND -24.67% 成交量 100
活跃榜（共 20 条）前 3 名：
1. HOSE:PNJ 23050 VND -6.87% 成交量 77040000
2. HOSE:HDB 28450 VND 1.61% 成交量 72470000
3. HOSE:VBB 14000 VND -1.06% 成交量 57640000常见问题
能只看某一个交易所的榜单吗？ 榜单是按整个国家排的，只传 country。只要某个交易所的，取回来以后按 exchange 自己筛一遍。
每个榜单有多少条？ 固定 20 条，不分页。
没有带 country 会怎样？ 请求会直接失败。榜单属于财务信息类的接口，这一类都必须带国家。
想看榜单里某只股票的报价和 K 线？ 把 original 拆开：冒号前面是市场代码，后面是产品代码。例如 HOSE:PNJ 就是 market=HOSE&symbol=PNJ，用在报价和 K 线接口上。
其它国家和市场
换一个国家只要改 country，例如美国 america、日本 japan、韩国 korea、印度 india。全部取值见国家与市场参数。想取单只股票的报价，可以接着看怎么用香港行情数据API接口获取实时报价；想在个股页面加上公司介绍，看怎么用印度行情数据API接口获取公司介绍。