根据姓名判断性别 API：姓名性别识别开发指南

姓名性别识别 API 根据姓名数据返回一个统计结果。它不读取身份证件，也不能确定某个人的性别认同。适合的用途包括数据汇总、受众分析和需要保留“不确定”结果的低风险流程。

NameGender 的响应不只包含 male 或 female。每次查询还会返回概率、样本量、置信等级、数据来源和实际参与匹配的名字。开发者可以据此决定采用结果、降低权重，或者保留为 null。

第一个 API 请求

创建 API 密钥后，使用 Authorization: Bearer 请求头发送 JSON。对于汉字和其他非拉丁文字，POST 请求可以避免手动处理 URL 编码。

curl -X POST https://namegender.com/api/v1/gender \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"伟","country":"CN"}'

一个响应包含以下核心字段：

{
  "query": "伟",
  "name": "伟",
  "gender": "male",
  "probability": 85,
  "sample_size": 0,
  "confidence": "unverified",
  "country": "CN",
  "source": "script",
  "matched_as": "wei"
}

这是真实响应，也说明了一个重要事实：sample_size 是 0，confidence 是 unverified。中文姓名数据来源不公布可审计的登记数量，所以结果依据的是文字规则 （source: "script"），而不是计数记录。答案可能正确，但它没有被计数支撑。

生产代码不应该只读取 gender。至少同时保存 probability、confidence 和 sample_size；否则你无法区分一个有数千条记录支撑的结果和一个没有计数的结果。

如何解释响应字段

probability: 90 不等于“这个人的性别有 90% 的可能性”。它表示当前数据中该姓名与主要类别的关联比例。这个区别决定了结果能否被安全使用。

中文姓名需要单独处理

中文姓名通常是姓在前、名在后。张伟 中的 张 是姓，伟 是名。如果系统把第一个拉丁字符组当作名字，Zhang Wei 可能错误地按姓氏 Zhang 查询。

最稳妥的做法是：

1. 已有独立名字字段时，只把名字发送到 name。
2. 只有全名时，优先发送汉字，并在响应中检查 name 和 last_name。
3. 只有拼音时，明确记录姓名顺序，不要默认第一个词一定是名字。

汉字通常比无声调拼音保留更多信息。wei 可以对应伟、薇、微、威和唯，这些字符的性别倾向并不相同。

批量姓名性别识别

不要为每个姓名建立一次网络连接。批量接口在一个请求中接收姓名数组，并保持结果顺序不变。

curl -X POST https://namegender.com/api/v1/gender/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names":["伟","静","王芳","Zhang Wei"],"country":"CN"}'

批量返回后，应把以下三类结果分开统计：高置信结果、需要复核的结果和 gender: null。把 null 自动改成概率最高的类别会让覆盖率看起来更高，但也会把不确定性藏起来。

推荐的生产规则

• 在界面和数据库中保留未知值。
• 针对自己的数据集选择概率阈值，不要复制通用阈值。
• 同时监控匹配率和回答后的准确率。
• 对中文数据分别测试汉字、拼音和混合输入。
• 招聘、医疗、金融、保险、法律或资格判断中不要根据姓名推断性别。

完整参数和错误响应见中文 API 文档。开始集成前，先用一小批具有已知标签的数据进行验证，比只看供应商给出的总准确率更可靠。