文本核名 · text-search
GET /v1/text-search
按商标名称检索注册库,容错召回同名/近似/义近,返回有效性、尼斯分类与相似度。
- 消耗:20 API 点
- 可用档位:全部(含免费版);伙伴国辖区(DE/IT/ES/TR/BX)需付费 API 套餐
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
q | string | 是 | 候选商标名称/关键词 |
nice | string | 否 | 尼斯分类号(1–45),限定商品类目;留空=不限类 |
live | 0/1 | 否 | 仅返回有效在册(Live);默认包含全部 |
limit | int | 否 | 返回条数上限,默认 50,最大 200 |
country | string | 否 | 目标市场(国家/地区代码),默认 US;可选 30+ 国/地区(英国用 UK),不支持的代码返回 400,错误信息列出当前可用清单;伙伴国 DE/IT/ES/TR/BX 经合作方提供,需付费 API 套餐,同为 20 点/次 |
请求示例
- cURL
- Python
curl "https://one1.cn/v1/text-search?q=NIKE&nice=25&live=1&limit=20" \
-H "Authorization: Bearer one1_live_xxxxxxxx"
import requests
r = requests.get(
"https://one1.cn/v1/text-search",
params={"q": "NIKE", "nice": "25", "live": 1, "limit": 20},
headers={"Authorization": "Bearer one1_live_xxxxxxxx"},
)
print(r.json())
响应示例
{
"results": [
{ "serial": "78787878", "mark": "NIKE", "nice": "25",
"status": "Registered", "is_live": 1, "score": 0.98, "tro_hit": false }
],
"count": 1,
"country": "US",
"jurisdiction": "US",
"source_label": "USPTO Trademark Database",
"official_source": "USPTO",
"coverage": { "scope": "full", "pct": null, "warning": "", "clearance_ok": true },
"request_id": "3f9a1c2b7d4e8f01",
"timestamp": "2026-10-10T07:20:01Z"
}
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
results[].serial | string | 商标序列号 |
results[].mark | string | 商标文本 |
results[].nice | string | 尼斯分类 |
results[].status | string | 法律状态 |
results[].is_live | 0/1 | 是否有效在册 |
results[].score | float | 相似度(0–1) |
results[].tro_hit | bool | true = 命中 One1 维护的 TRO 维权高危库;false = 未命中,不等于无维权风险。仅布尔,不返回权利人名录 |
count | int | 结果条数 |
country | string | 实际检索的辖区代码(默认 US) |
jurisdiction | string | 结果所属辖区(本地辖区返回) |
source_label / official_source | string | 数据来源说明与官方局简称(如 USPTO Trademark Database / USPTO),本地辖区返回 |
coverage.scope | string | 所查辖区库的覆盖口径:full / partial / thin / very-thin / image-only / unverified |
coverage.warning | string | 覆盖警示文案(空串 = 无警示),请原样展示给终端用户;文案来自覆盖度配置,可能提及该库的数据截止时间 |
coverage.clearance_ok | bool | 是否可把「无匹配」当作可注册的参考依据;仅 coverage.scope 为 full 时为 true |
coverage.pct / coverage.usable_pct | float 或 null | 覆盖率 / 可用记录比例的估算,仅在有统计基准时给出,否则为 null 或不出现 |
request_id | string | 本次请求的追踪 ID,与响应头 X-Request-Id 同值(调用方自带该头则原样回显);排障时请提供 |
timestamp | string | 服务端响应时间,UTC ISO 8601 带 Z(如 2026-10-10T07:20:01Z);不代表数据新鲜度 |
伙伴国(DE/IT/ES/TR/BX)
当 country 为经伙伴数据源检索的国家(当前为 DE、IT、ES、TR、BX,以 GET https://one1.cn/api/coverage?country=XX 返回 scope=partner 为准)时,响应顶层额外带 country、source: "partner:ruiguan"、verdict_semantics: "partner" 与 score_kind: "partner_risk",显式标注来源,不得当本地美国结果渲染;结果项 is_live 同为 0/1。
注意:伙伴国结果的 score 是合作方的风险分口径(由 score_kind: "partner_risk" 标出),与本地辖区 0–1 的相似度不可直接比较;本地辖区不带 score_kind。伙伴国为实时数据源,响应不带 coverage 与 jurisdiction / source_label / official_source,覆盖口径见 GET https://one1.cn/api/coverage?country=XX。
伙伴国辖区经合作方提供,需付费 API 套餐,同为 20 点/次,且只从套餐月度点扣除(赠送点不可用);免费版调用返回 403 paid_plan_required,未扣点。