Skip to content

参数与编码 ​

全站接口目前都是 GET,参数一律放在查询字符串里。这一页把容易踩坑的细节集中说明。

基本形式 ​

https://api.sco1.cn/Interface/xxx/?参数1=值1&参数2=值2
  • ? 之后是查询字符串,多个参数用 & 连接。
  • 参数名区分大小写,以接口详情页的参数表为准。
  • 不传可选参数时使用接口默认值;不要传空字符串去「表示默认」。

中文与特殊字符必须编码 ​

下面这些字符直接拼进 URL 会出错:空格、&、#、+、%、?、/,以及所有非 ASCII 字符。

js
// 正确
const q = encodeURIComponent('你好')
fetch(`https://api.sco1.cn/Interface/Pinyin/?text=${q}`)

// 错误:中文和空格未编码,& 会被当成参数分隔符
fetch('https://api.sco1.cn/Interface/Pinyin/?text=你好 世界&a=1')
python
# requests 会自动编码,不要自己拼
requests.get(url, params={'text': '你好 世界'}, timeout=10)
php
$url = 'https://api.sco1.cn/Interface/Pinyin/?text=' . rawurlencode('你好 世界');

& 会截断参数值

& 是参数分隔符。如果值里本身含 &(例如一个网址),未编码时后面的内容会被当成另一个参数。这是调试中最常见的一类「参数明明传了却说缺参」。

常见类型 ​

类型写法例子
int十进制整数?n=3、?page=2
string文本,需编码?symbol=XAU、?text=你好
枚举参数表 enum 列出的值之一?action=list、?name=ssq
布尔按参数表约定,通常用 1/0 或 true/false?seen=1

枚举值传错会返回 400,错误信息里一般会列出可选值。

数组与多值 ​

只有当参数表明确说明支持多值时,才用重复参数名或逗号分隔:

?ids=1,2,3
?tag=a&tag=b

不要自行假设接口支持数组形式,以详情页参数表为准。

空值与默认值 ​

  • 不传 = 使用默认值。
  • 传 ?n=(空字符串)不等于不传,有些接口会按 0 或非法值处理。
  • 数字参数越界(例如 count 要求 1–30 却传 100)会被接口截断或返回 400。

key 参数 ​

key 是全站通用的身份参数,不写在各接口的参数表里。需要时追加到查询字符串:

https://api.sco1.cn/Interface/GoldPrice/?symbol=XAU&key=YOUR_API_KEY

如果同时有业务参数,用 & 连接即可。站内详情页的调试面板有独立的「API Key(可选)」输入框。详见 鉴权与 API Key。

超时与重试 ​

  • 依赖第三方数据源的接口可能有 10–30 分钟缓存,返回不一定实时。
  • 建议给请求设置 10–15 秒超时。
  • 遇到 429 用指数退避重试;遇到 502 / 503 稍后重试,不要立刻死循环。

详见 限流与配额 和 响应格式与错误码。

接口数据实时读取自站点数据库