快速开始 - API 开发者文档

注册账号获取 API Key 发起调用返回结果

所有 API 接口共用同一套鉴权与调用协议，本文讲解的流程对所有接口通用。建议先通过免费额度完成首次调用，再决定是否购买次数包。
注意：免费额度仅适用于单次售价不高于 ¥0.08/次 的接口，售价更高的接口调用不参与免费额度，将按会员折扣价从余额扣费。

STEP 01

注册账号

使用任何接口前，你需要一个有效的账号。注册过程约 1 分钟，只需邮箱与密码即可完成。

打开注册页面，填写邮箱、设置密码（至少 8 位，建议包含大小写字母与数字），勾选同意服务条款。
提交表单即注册成功（无需邮箱验证码），账号即时生效并自动登录。
注册成功即赠送新用户免费调用次数与开户奖励余额（用于调试接口，不产生费用），并自动创建一把「默认密钥」。

请使用真实有效的邮箱。后续的密钥安全通知、余额预警、发票信息都将发送到此邮箱，且部分安全操作需要邮箱验证。

STEP 02

获取 API Key

API Key 是你的接口调用凭证，即 App Key（接口调用密钥，形如 sk_live_...）。

注册时系统已自动创建一把「默认密钥」，该密钥默认为禁用状态。登录后进入「控制台 → API 密钥」完成启用，或直接创建新密钥。

登录控制台，进入API 密钥页面。
若使用默认密钥，点击「启用」即可；也可点击「创建密钥」，设置密钥名称（如「生产环境」）、选择环境（生产 / 开发测试）与权限范围（读写 / 只读），并可为密钥配置每日、每月调用限额与 IP 白名单。
创建成功后页面会完整展示一次 App Key（生产 / 预发环境以 sk_live_ 开头，开发测试环境以 sk_test_ 开头），请立即复制并妥善保存。

App Key（调用密钥） sk_live_4f8a2b9c0d3e5f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f

App Key 仅展示一次，请立即保存。App Key 等同于你的账号密码，切勿写入前端代码、提交到 Git 仓库或通过明文传输。如泄露，请立即在控制台吊销并重新创建。

建议为不同环境（本地 / 测试 / 生产）创建多把密钥并设置独立名称，便于审计与吊销。每把密钥可单独设置读写权限、可调用接口范围与 IP 白名单。

STEP 03

发起第一次调用

以「实时天气 · 单点查询」接口为例。调用统一使用 GET 请求，默认返回 JSON 格式，请求参数通过 URL 查询串传递，鉴权信息直接在接口地址后拼接 ?key=<你的App Key> 即可。平台同时支持 Authorization: Bearer <你的App Key> 请求头方式，生产环境建议使用请求头，避免密钥出现在访问日志与浏览器历史中。

请求地址

GET http://www.shujuyu.cn/v1/api/weather/query JSON

常用编程语言示例

# 实时天气 · 单点查询（URL 携带 App Key）
curl -G "http://www.shujuyu.cn/v1/api/weather/query" \
  --data-urlencode "key=sk_live_4f8a2b9c0d3e5f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f" \
  --data-urlencode "city=北京"

# 实时天气 · 单点查询（Python 示例）
import requests

res = requests.get(
    "http://www.shujuyu.cn/v1/api/weather/query",
    params={
        "key": "sk_live_4f8a2b9c0d3e5f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f",
        "city": "北京",
    },
)
data = res.json()
print(data["code"], data["msg"])        # 例如 200 success
print(data["data"]["daily"][0])         # 例如 {'date': '2026-07-01', 'weather_desc': '毛毛雨', 'temp_max': 31.5}

// 实时天气 · 单点查询（Node.js 示例）
// 注意：App Key 请存放在服务端，切勿暴露在浏览器端。
const APP_KEY = 'sk_live_4f8a2b9c0d3e5f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f';

const res = await fetch('http://www.shujuyu.cn/v1/api/weather/query?key=' + encodeURIComponent(APP_KEY) + '&city=' + encodeURIComponent('北京'));
const data = await res.json();
console.log(data.code, data.msg);
console.log(data.data.daily[0].weather_desc, data.data.daily[0].temp_max);

<?php
// 实时天气 · 单点查询（PHP 原生 cURL 示例）
$appKey = 'sk_live_4f8a2b9c0d3e5f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f';

$ch = curl_init('http://www.shujuyu.cn/v1/api/weather/query?key=' . urlencode($appKey) . '&city=' . urlencode('北京'));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
]);
$res = curl_exec($ch);
curl_close($ch);
echo $res; // 输出 JSON 响应
?>

请求参数说明

请求参数说明
参数	类型	必填	默认值	说明
city	String	否	—	城市名，如 `北京`。与 `lat` / `lng` 二选一。
lat	Float	否	—	纬度，如 `39.9042`。与 `city` 二选一，需配合 `lng` 使用。
lng	Float	否	—	经度，如 `116.4074`。与 `city` 二选一，需配合 `lat` 使用。

STEP 04

错误处理

所有接口返回统一的结构体：业务成功时 code 为 200，失败时为对应业务错误码，并附带 msg 提示与 request_id（可用其向技术支持定位请求），便于快速定位问题。

HTTP 状态码反映传输层是否成功（多为 200 / 400 / 401 / 429 / 500），具体业务是否成功以响应体中的 code 为准。

常见错误码

错误码说明
code	说明	处理建议
200	调用成功	正常返回直接取用 data 即可。
400000	请求参数错误	检查参数名、格式与取值。
401000	认证失败：密钥无效 / 已禁用 / 已过期	核对密钥是否正确、密钥状态与有效期。
401002	缺少 API 认证参数	请求未携带 key，通过 URL 参数 key 或请求头 Authorization 传递密钥。
402000	账户余额不足	前往「余额充值」页充值后重试。
403000	无访问权限：权限不足、接口范围不符或 IP 不在白名单	确认密钥权限与调用 IP 白名单。
404001	接口或端点不存在	核对接口地址与方法，确认接口已上架。
409000	请求冲突	稍后重试。
422000	参数校验失败	按接口文档核对参数名、类型与取值范围。
429001	请求频率超限（QPS）	降低请求频率或升级套餐；建议实现指数退避重试。
429002	分钟级调用频率超限	降低请求频率或升级套餐；建议实现指数退避重试。
429003	小时级调用额度已用完	升级套餐提升额度，或整点后重试。
429004	今日调用额度已用完	升级套餐提升额度，或次日重试。
500000	服务器内部错误	附响应中的 `request_id` 提交工单。
502000	服务暂时不可用	稍后重试；持续异常请联系技术支持。
503000	服务暂时不可用	稍后重试。
504000	请求超时	稍后重试。

完整错误码与超时重试策略请参见上文常见错误码表格。建议调用端为 429 / 5xx 实现指数退避重试，避免在限流下反复请求。

下一步

你已经完成第一次调用。下面几个方向可以继续深入：

浏览全部接口从全部已上架接口中找到适合你的数据服务。去 API 市场在线调试接口无需写代码即可在线填入参数，实时查看返回结果。打开调试器了解会员权益了解 VIP 等级、调用额度与 QPS 提升等进阶权益。查看会员