API 接入指南

开发者文档

按顺序完成第一次调用，再按需查看分页与异常处理。

查看数据产品进入控制台

已有账号、Key 和已发布产品后，约 5 分钟完成示例调用。

01 选择已发布产品02 创建 API Key03 获取服务状态04 调用数据接口

开始之前

先确认产品可用，再准备调用凭据。

产品已发布

在数据产品中选择“正式 API 已发布”的产品，复制其 API 路径。固定样例可看，不代表正式 API 已可调用。

API Key 已创建

在客户控制台登录完成产品开通与授权，再创建有该产品权限的 Key。

文档示例 API 地址https://api.wanxiangdata.com以正式发布后的服务地址为准。

保护 API Key

只在服务端或安全的客户程序中使用。不要放进前端代码、Git 仓库或公开日志。

完成首次调用

下面三步展示状态核验、列表和详情调用。默认使用 cURL；每段代码均可复制。

先替换 <API_KEY> 和 <PRODUCT_PATH>。产品路径来自已发布产品详情页，例如形如 /v1/drugs；该路径仅作格式说明，产品待发布时不能调用。查询详情时，把列表中的记录 ID 填入 <RECORD_ID>。

获取服务状态

此免费接口返回服务 state；调用数据接口前可用它确认服务是否开放。

查询服务状态 · cURL

curl 'https://api.wanxiangdata.com/v1/service/status' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

查询服务状态的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com/v1/service/status",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com/v1/service/status", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

查询列表

使用 API Key 调用。每次成功列表响应均单独消耗一次试用或计费，包括空列表；相同参数再次请求和网络重试成功也再次计算。

获取最多 20 条摘要 · cURL

curl 'https://api.wanxiangdata.com<PRODUCT_PATH>?page_size=20' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

获取最多 20 条摘要的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com<PRODUCT_PATH>?page_size=20",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com<PRODUCT_PATH>?page_size=20", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

按 ID 查询详情

从列表的 data 中取一条记录的 id。详情每次成功响应也单独消耗试用或计费；合法未找到的详情同样计费。若列表为空，可跳过这步。

获取单条完整记录 · cURL

curl 'https://api.wanxiangdata.com<PRODUCT_PATH>/<RECORD_ID>?read_context=<READ_CONTEXT>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

获取单条完整记录的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com<PRODUCT_PATH>/<RECORD_ID>?read_context=<READ_CONTEXT>",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com<PRODUCT_PATH>/<RECORD_ID>?read_context=<READ_CONTEXT>", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

看懂返回结果

以下只展示字段结构，不是真实数据，也不是可复制的完整响应。

{
  "data": [],
  "meta": {
    "data_version": "<DATA_VERSION>",
    "read_context": "<READ_CONTEXT>",
    "read_context_expires_at": "<ISO_TIME>"
  },
  "pagination": {
    "page_size": 20,
    "has_more": false,
    "next_cursor": null
  }
}

data

列表是摘要数组；详情是单条完整记录。成功返回空列表表示没有匹配结果。

meta

列表包含 data_version、read_context 和过期时间；详情只包含 data_version。请求编号在响应头 X-Request-ID，账务到控制台查看。

pagination.next_cursor

列表有下一页时返回游标；没有下一页时为空。详情响应不需要分页。

如何判断结果

成功数据请求即单独计费或消耗试用，包括空结果；失败不收费。状态未知时用请求编号核验账务。

分页与详情

先用列表定位记录，再按单个 ID 读取完整字段。

列表 GET <PRODUCT_PATH> 的 page_size 为 1–20，默认 20。需要下一页时，将本页返回的 pagination.next_cursor 作为下一次列表请求的 cursor；每页成功响应都会单独计费或消耗试用。详情路径为 GET <PRODUCT_PATH>/<RECORD_ID>，每次只读一条。列表返回的 meta.read_context 可供详情读取同一数据快照。

读取下一页 · cURL

curl 'https://api.wanxiangdata.com<PRODUCT_PATH>?page_size=20&cursor=<NEXT_CURSOR>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

读取下一页的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com<PRODUCT_PATH>?page_size=20&cursor=<NEXT_CURSOR>",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com<PRODUCT_PATH>?page_size=20&cursor=<NEXT_CURSOR>", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

可用筛选条件、字段和更新记录以对应产品详情页为准。URL 中的 /v1/ 是当前接口路径版本。

字段模糊筛选

按产品开放的字段查找文字片段，先取得摘要，再按 ID 读取完整详情。

每个产品详情页都提供可交互的字段选择和两步请求示例。实际开放字段与配置版本来自该产品的 query_capabilities.filter_operators 和 query_capabilities.revision。只有开放 contains 的字段才能传 字段名__contains；未配置字段时暂不支持模糊搜索。q 仅在开放 name 时可作为 name__contains 的别名，两者不能同传。

模糊搜索调用产品集合端点，最多返回 20 条摘要，并按列表请求计费或消耗试用。从摘要结果中取记录 ID 和列表响应的 meta.read_context，再按单个 ID 调用详情接口读取完整字段，详情请求另行计费。详情 URL 只需 ID 和读取上下文，不传模糊条件。多个文字条件取交集；百分号、下划线和反斜杠按普通文字匹配。API Key 还须拥有目标字段权限。配置版本变化后请从第一页开始；只有 target_version 的普通列表可搭配模糊筛选，since_version 增量不可混用。以下查询格式中的 name 仅为占位示意，实际可用字段请以产品页为准。

搜索摘要列表 · cURL

curl 'https://api.wanxiangdata.com<PRODUCT_PATH>?name__contains=<SEARCH_TEXT>&page_size=20' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

搜索摘要列表的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com<PRODUCT_PATH>?name__contains=<SEARCH_TEXT>&page_size=20",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com<PRODUCT_PATH>?name__contains=<SEARCH_TEXT>&page_size=20", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

按结果 ID 读取完整详情 · cURL

curl 'https://api.wanxiangdata.com<PRODUCT_PATH>/<RECORD_ID>?read_context=<READ_CONTEXT>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

按结果 ID 读取完整详情的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com<PRODUCT_PATH>/<RECORD_ID>?read_context=<READ_CONTEXT>",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com<PRODUCT_PATH>/<RECORD_ID>?read_context=<READ_CONTEXT>", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

按日期筛选

查询已发布记录中某个日期区间。

仅在产品详情标明支持时使用。start_date 和 end_date 使用 YYYY-MM-DD，包含起止日期，也可以只传一个边界。date_field 选择 date 或 issued_on；未传时固定使用 date；如果产品只支持 issued_on，须显式传 date_field=issued_on。示例中的 date_field 请按该产品的支持字段替换。

按日期查询列表 · cURL

curl 'https://api.wanxiangdata.com<PRODUCT_PATH>?start_date=2026-01-01&end_date=2026-01-31&date_field=date&page_size=20' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

按日期查询列表的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com<PRODUCT_PATH>?start_date=2026-01-01&end_date=2026-01-31&date_field=date&page_size=20",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com<PRODUCT_PATH>?start_date=2026-01-01&end_date=2026-01-31&date_field=date&page_size=20", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

选择产品不支持的日期字段会报错且不计费。该字段为空的记录不进入筛选结果；成功返回空列表仍计费。日期筛选是普通列表查询，继续使用标准游标分页。

按数据版本同步

从已保存的完整版本更新到指定的发布版本。

先在免费产品目录查看 current_version 及产品是否支持版本同步。首次建库应完整遍历列表，或使用已有全量交付，并保存其 data_version。已有基线后，在同一个列表接口传 since_version；target_version 可省略，此时首个请求固定当前版本。也可只传 target_version 固定普通列表；此时可搭配日期或文本筛选。建立完整同步基线时，须在该目标版本无筛选遍历所有页。只有传 since_version 做增量查询时，才不能与日期或文本筛选混用。

查询两个版本之间的当前状态差异 · cURL

curl 'https://api.wanxiangdata.com<PRODUCT_PATH>?since_version=<BASE_VERSION>&target_version=<TARGET_VERSION>&page_size=20' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

查询两个版本之间的当前状态差异的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com<PRODUCT_PATH>?since_version=<BASE_VERSION>&target_version=<TARGET_VERSION>&page_size=20",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com<PRODUCT_PATH>?since_version=<BASE_VERSION>&target_version=<TARGET_VERSION>&page_size=20", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

版本响应的 meta.base_version 为基线，meta.data_version 为目标版本。逐页读取并保存 added、updated、removed；新增和更新按 ID 携带 meta.read_context 查询完整详情。updated 只表示业务字段改变，单纯采集日期变化不会触发。removed 只有 ID，表示目标版本不在平台数据集中，不表示官方注销，也无需再查详情。

先暂存全部页和所需详情，再一起应用变更并更新本地基线；任何一步失败都保留旧基线。签名游标与读取上下文当前有效期为 24 小时，请在响应标示的过期时间前完成读取。游标过期时，从第一页使用原来的 since_version 和准确的 target_version 重试。历史版本尚未准备或业务比较规则不兼容时返回 409 FULL_SYNC_REQUIRED，应重新全量建库；版本已撤回或不可用时返回 410。成功空差异、只有移除项的分页及成功重试同样逐次计费。

超时或报错怎么办

先保留请求信息，再决定是否重试。

超时后先做这件事

保存请求路径、参数、时间及响应头 X-Request-ID。有请求编号时，用同一个 API Key 免费查询 GET /v1/requests/<request_id> 核验本次账务。没有请求编号时，联系支持协助定位；再次发起数据 GET 若成功，会单独计费或消耗试用。

免费核验请求状态 · cURL

curl 'https://api.wanxiangdata.com/v1/requests/<REQUEST_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

免费核验请求状态的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com/v1/requests/<REQUEST_ID>",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com/v1/requests/<REQUEST_ID>", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

遇到的情况	如何识别	下一步
Key 无效	401	检查 Key 是否正确、有效。
无权调用	403	确认产品已开通、Key 拥有该产品和操作权限。
参数有误	400 / 422	根据 `error.message` 修正请求。
请求冲突或处理中	409	按错误信息检查请求；已有请求编号时先核验其状态。
请求过于频繁	429	降低调用频率，稍后按响应提示重试。
服务或数据暂不可用	5xx	查看 `error.retryable`；已有请求编号时先免费核验账务，再决定是否重试。
网络超时	客户端未取得响应	有请求编号时先免费核验；再次成功请求会另行计费。

如果请求状态仍未明确，请保留请求编号并联系支持。

免费费用 API

用当前 API Key 查询其自己的调用与账务记录。

GET /v1/usage/summary 返回汇总、按日或按月趋势、按产品与操作的汇总；GET /v1/usage/records 返回分页明细。两者均需 Bearer API Key，免费且不执行数据查询。示例按产品和列表操作筛选；替换 <DATASET_CODE>，或移除 dataset_code 与 operation 以查看此 Key 授权范围内的全部记录。Key 无权查看的产品或操作不可筛选，也不会进入未筛选结果。

免费查询调用汇总 · cURL

curl 'https://api.wanxiangdata.com/v1/usage/summary?period=month&granularity=day&dataset_code=<DATASET_CODE>&operation=list' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

免费查询调用汇总的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com/v1/usage/summary?period=month&granularity=day&dataset_code=<DATASET_CODE>&operation=list",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com/v1/usage/summary?period=month&granularity=day&dataset_code=<DATASET_CODE>&operation=list", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

免费查询调用明细 · cURL

curl 'https://api.wanxiangdata.com/v1/usage/records?dataset_code=<DATASET_CODE>&operation=list&limit=20&offset=0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

免费查询调用明细的 Python 与 JavaScript 示例

在安全的服务端环境设置 WANXIANG_API_KEY。Python 需要 requests；JavaScript 示例使用 Node.js 的 fetch。

Python · requests

import os
import requests

response = requests.get(
    "https://api.wanxiangdata.com/v1/usage/records?dataset_code=<DATASET_CODE>&operation=list&limit=20&offset=0",
    headers={"Authorization": f"Bearer {os.environ['WANXIANG_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
request_id = response.headers.get("X-Request-ID")
payload = response.json()
print(request_id, payload)

JavaScript · fetch

const response = await fetch("https://api.wanxiangdata.com/v1/usage/records?dataset_code=<DATASET_CODE>&operation=list&limit=20&offset=0", {
  headers: { Authorization: "Bearer " + process.env.WANXIANG_API_KEY },
});
if (!response.ok) throw new Error("HTTP " + response.status);
const requestId = response.headers.get("X-Request-ID");
const payload = await response.json();
console.log(requestId, payload);

period=day|week|month 选择当天、本周或本月，默认本月；granularity=day|month 选择趋势按天或按月。也可同时传 start_date 和 end_date 自定义含边界的日期范围，最长 370 天，按 Asia/Shanghai 统计。operation 可选 list 或 detail；明细使用 limit（1–100）和 offset 分页。汇总和明细统计已结算的逻辑请求，失败请求会单列且不计费。金额 amount_micro 是整数字符串，1 元等于 1,000,000 微元；不要把字符串当浮点金额累加。当前 Key 的试用与付费计数可在汇总中核对，更多工作空间费用记录请登录控制台。

开始之前

完成首次调用

获取服务状态

查询列表

按 ID 查询详情

看懂返回结果

分页与详情

字段模糊筛选

按日期筛选

按数据版本同步

超时或报错怎么办

免费费用 API

更多资源