接口概述
一句话说明
samename.query 是「按姓名查全国同名人数」的接口：
传入姓名，返回与该姓名完全相同的人数（count）。
优先读本地缓存；缓存未命中时调用上游数据源，上游不可用（含令牌未维护 / 已过期、返回非成功）时
自动转大模型估算兜底，并把结果落库复用。
| 请求地址 | https://api.xujian.tech/openapi/samename/query |
|---|---|
| 请求方式 | GET（name / xb / xzqh 放 Query String） |
| 鉴权方式 | 请求头 X-API-Key |
| 接口编码 | samename.query |
| 收费类型 | PER_CALL（按次计费，0.1000 元/次） |
| 计费特殊规则 | 查得计费：姓名不足 2 字、上游与大模型均不可用时， 返回失败且不扣费；令牌未维护不算失败，走大模型兜底并正常计费 |
| 响应格式 | JSON，Content-Type: application/json;charset=UTF-8 |
| 是否需要授权 | 否（无需授权，API Key 有效且余额充足即可调用） |
| 典型用途 | 趣味重名查询、起名避雷参考、人口统计学小工具 |
快速开始
# 查询「示例姓名」的全国同名人数
curl -s -G "https://api.xujian.tech/openapi/samename/query" \
--data-urlencode "name=示例姓名" \
-H "X-API-Key: 你的APIKey"name 怎么填
name 是客户输入的姓名（姓 + 名），必填且至少 2 个字。
不足 2 字会直接返回失败且不计费。xb（性别，默认 3=不限）、
xzqh（行政区划，默认 100000=全国）为可选参数。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
X-API-Key | String | 是 | 开发者 API Key |
| 参数名 | 类型 | 必填 | 默认值 | 示例 | 说明 |
|---|---|---|---|---|---|
name | String | 是 | — | 示例姓名 | 姓名，至少 2 个字；不足 2 字返回失败且不计费 |
xb | Integer | 否 | 3 | 3 | 性别：1男 2女 3不限；影响同名人数统计口径 |
xzqh | String | 否 | 100000 | 100000 | 行政区划代码，100000=全国；限定查询地域范围 |
响应参数
业务字段
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
name | String | 示例姓名 | 姓名（回显客户输入的 name） |
count | Integer | 12345 | 全国与该姓名完全相同的人数 |
gender | Integer | 3 | 性别参数（xb）回显：1男 2女 3不限 |
region | String | 100000 | 行政区划参数（xzqh）回显，100000=全国 |
source | Integer | 1 | 数据来源：1=上游真实返回，2=大模型估算（兜底） |
fromCache | Boolean | false | 是否命中本地缓存（true=直接读库返回，false=本次首次查询并落库） |
公共字段
| 字段 | 类型 | 说明 |
|---|---|---|
apiCode | String | 接口编码 samename.query |
apiName | String | 接口名称 |
chargeType | String | 计费类型 |
balance | BigDecimal | 调用完成后（已扣费）的账户余额（元） |
costMs | Long | 本次调用耗时（毫秒） |
口径与边界提示
① count 表示「与该姓名完全相同（同姓且同名）」的人数，不是同姓人数；
② source=2 表示结果为大模型估算兜底，数字仅供参考（规则：存在该姓名通常 10000–50000 之间，
仅当姓氏根本不存在才为 0，否则不低于 30），权威数据以 source=1 为准；
③ 首次查询的结果（无论来源）会落库复用，之后相同查询直接读库，规避上游令牌过期；
④ 若需刷新某姓名的缓存值，请联系平台运营清理 same_name_record 对应记录。
响应示例
成功（上游真实返回，source = 1，code = 0）
{
"code": 0,
"msg": "success",
"data": {
"name": "示例姓名",
"count": 12345,
"gender": 3,
"region": "100000",
"source": 1,
"fromCache": false,
"apiCode": "samename.query",
"apiName": "全国同名同姓人数查询",
"chargeType": "PER_CALL",
"balance": 99.9000,
"costMs": 280
}
}成功（命中本地缓存，fromCache = true，code = 0）
{
"code": 0,
"msg": "success",
"data": {
"name": "示例姓名",
"count": 12345,
"gender": 3,
"region": "100000",
"source": 1,
"fromCache": true,
"apiCode": "samename.query",
"apiName": "全国同名同姓人数查询",
"chargeType": "PER_CALL",
"balance": 99.8000,
"costMs": 12
}
}失败（姓名不足 2 字）—— 不收费
{
"code": 500,
"msg": "姓名至少 2 个字",
"data": null
}失败（上游与大模型均不可用）—— 不收费
{
"code": 500,
"msg": "数据服务暂时不可用（上游与大模型均不可用），本次调用不计费",
"data": null
}错误码与常见失败原因
| code | msg（示例） | 处理建议 |
|---|---|---|
| 0 | success | 调用成功 |
| 500 | 缺少请求头 X-API-Key | 补充 X-API-Key |
| 500 | API Key 无效 / API Key 已停用 | 检查 Key 或重新启用 |
| 500 | 客户不存在或已停用 | 联系平台（可联系微信xujian_cq） |
| 500 | 接口不存在或已停用 | 确认 samename.query 当前是否维护中 |
| 500 | 余额不足，请先充值。可联系微信xujian_cq | 充值后重试，余额不足不扣费 |
| 500 | 姓名至少 2 个字 | 补齐 name（≥2 字）；不计费 |
| 500 | 数据服务暂时不可用（上游与大模型均不可用），本次调用不计费 | 稍后重试；不计费 |
多语言代码示例
Java（Hutool）
String body = HttpRequest.get("https://api.xujian.tech/openapi/samename/query")
.form("name", "示例姓名")
.header("X-API-Key", apiKey)
.timeout(15000)
.execute()
.body();
JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") != 0) {
System.out.println("查询失败（不收费）：" + json.getStr("msg"));
return;
}
JSONObject data = json.getJSONObject("data");
System.out.println("姓名：" + data.getStr("name"));
System.out.println("同名人数：" + data.getInt("count"));
System.out.println("数据来源：" + (data.getInt("source") == 1 ? "上游真实" : "大模型估算"));Python
import requests
def get_same_name_count(api_key: str, name: str) -> dict | None:
"""按姓名查全国同名人数；查不到返回 None 且不扣费"""
resp = requests.get(
"https://api.xujian.tech/openapi/samename/query",
params={"name": name},
headers={"X-API-Key": api_key},
timeout=20,
)
result = resp.json()
if result.get("code") != 0:
print("查询失败（不收费）：", result.get("msg"))
return None
return result["data"]
if __name__ == "__main__":
info = get_same_name_count("你的APIKey", "示例姓名")
if info:
print(info["name"], info["count"], "来源:", info["source"])JavaScript（浏览器 / Node 18+）
const params = new URLSearchParams({ name: "示例姓名" });
const resp = await fetch(`https://api.xujian.tech/openapi/samename/query?${params}`, {
headers: { "X-API-Key": API_KEY },
});
const { code, msg, data } = await resp.json();
if (code === 0) {
console.log(data.name, data.count, "来源:", data.source);
} else {
console.warn("查询失败（不收费）：", msg);
}常见问题（FAQ）
samename.query 接口怎么收费？
samename.query 的收费类型为 PER_CALL（按次计费），当前单价 0.1000 元/次，调用前校验余额，余额不足返回「余额不足，请先充值。可联系微信xujian_cq」且不扣费；充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。
name 必填吗？至少几个字？
必填。name 是客户输入的姓名，至少 2 个字；
不足 2 字会直接返回失败且不计费。
返回哪些字段？source 是什么？
返回 name（回显）、count（同名人数）、gender、
region（参数回显）、source（数据来源：1=上游真实返回 / 2=大模型估算）、
fromCache（是否命中本地缓存），以及公共字段。
上游接口不可用时会怎样？
上游数据源返回非成功，或上游令牌未维护 / 已过期时，接口自动调用大模型根据姓名估算一个人数兜底， 并把结果落库；之后相同查询直接读库返回。仅当上游与大模型均不可用时返回失败且不计费。
大模型估算的数字准吗？
大模型估算为兜底方案，数字仅作参考（规则：存在该姓名通常 10000–50000 之间，
仅当姓氏根本不存在才为 0，否则不低于 30）。如需权威数据请以 source=1（上游真实返回）为准。
调用需要签名或加密吗？
不需要。XAPI 的接口仅校验请求头 X-API-Key，不做签名、时间戳或加密。
