您需要在周五之前告诉产品经理一个名称是否可以注册商标,如果不能,哪些类别仍然开放。在本指南结束时,您将能够使用来自Zyla API Hub的单个API密钥检查商标可用性,并提取所有者和商标详细信息,将其插入到您的应用程序、CI作业或审核流程中,并快速返回可操作的结果。
此API提供的内容及使用时机
在Zyla API Hub上的商标搜索API公开了三个读取端点:
- 搜索:按名称或邮政编码查找所有者并检索其注册商标。
- 商标可用性:检查一个关键字是否可用,以及哪些尼斯类别可用或已被占用,并附带相关的序列号。
- 商标搜索:基于关键字的搜索,返回核心注册元数据(状态、所有者、申请/注册日期等)。
典型的集成包括在产品发布前进行品牌筛选、市场列表审核、新卖家名称的结账门槛,以及跨管辖区和类别的内部审计。
在Zyla API Hub上开始
打开API的市场页面并订阅以获取您的密钥。每个请求的身份验证通过Authorization: Bearer YOUR_API_KEY进行。
- 访问商标搜索API的7天试用开始页面。
- 点击订阅(或在可用时点击开始免费试用)以获取API密钥。
- 在Zyla API Hub上的任何API中使用相同的密钥。计费为订阅+配额,而不是按调用计费。对于这个第一个API,您可以从7天试用或50个请求开始。请查看API页面以获取当前访问选项和定价。
您将调用的端点
1) 搜索
方法: GET
URL: https://zylalabs.com/api/1495/trademark-search-api/1236/search
功能: 按所有者名称或邮政编码进行搜索,并返回该所有者找到的商标的详细信息。当所有者的地址发生变化时,可能会出现重复的所有者。
需要身份验证。此示例未记录请求参数。
cURL(复制粘贴):
curl -s -X GET "https://zylalabs.com/api/1495/trademark-search-api/1236/search" \
-H "Authorization: Bearer YOUR_API_KEY"
JSON响应(官方示例):
{
"count": 1,
"items": [
{
"name": "VIAJO.COM INC.",
"address1": "4225 Executive Square, Suite 325",
"address2": null,
"city": "La Jolla",
"state": "CA",
"country": "US",
"postcode": "92037",
"trademarks": [
{
"keyword": "CLICK Y VIAJA",
"registration_number": "2847107",
"serial_number": "75928638"
}
]
}
]
}
您实际使用的内容:计数以确定结果集的大小;每个所有者的名称和地址字段以确认身份;在商标下,关键字加上registration_number和serial_number用于下游检查或UI链接。
2) 商标可用性
方法: GET
URL: https://zylalabs.com/api/1495/trademark-search-api/1237/trademark-availability
功能: 返回给定关键字是否可用,并列出available_classes、unavailable_classes和相关的serial_numbers。需要身份验证。此示例未记录请求参数。
当您需要一个是/否和类别细分以推动产品决策时使用此功能。例如,如果unavailable_classes与目标类别集重叠,命名服务可能会阻止提交。
3) 商标搜索
方法: GET
URL: https://zylalabs.com/api/1495/trademark-search-api/1238/trademark-search
功能: 关键字搜索,返回商标名称、序列号和注册号、状态信息、所有者详细信息以及申请/注册日期。需要身份验证。搜索类型的行为在列表中以高层次描述,包括排除死商标的“活动”类型;请查阅API页面以获取参数的具体信息。
使用此功能以获取更丰富的细节:status_label/code/definition、filing_date、registration_date和所有者数据,以围绕候选商标构建完整的个人资料页面或内部仪表板。
复制粘贴代码以发布
Python示例:调用搜索并提取所有者和商标ID
此示例调用搜索端点,然后打印所有者和第一个商标的序列号和注册号。它使用与上面的cURL示例相同的端点。
import os
import requests
API_KEY = os.environ.get("ZylaApiKey", "YOUR_API_KEY")
url = "https://zylalabs.com/api/1495/trademark-search-api/1236/search"
headers = {
"Authorization": f"Bearer {API_KEY}",
}
resp = requests.get(url, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
print(f"总所有者:{data.get('count')}")
for owner in data.get('items', []):
print("所有者:", owner.get('name'))
addr = ", ".join(filter(None, [
owner.get('address1'),
owner.get('address2'),
owner.get('city'),
owner.get('state'),
owner.get('postcode'),
owner.get('country'),
]))
print("地址:", addr)
for tm in owner.get('trademarks', []):
print(" - 商标:", tm.get('keyword'))
print(" 注册号:", tm.get('registration_number'))
print(" 序列号:", tm.get('serial_number'))
实施注意事项:
- 身份验证:始终包括Authorization: Bearer YOUR_API_KEY。
- 超时:设置适合您工作负载的客户端超时。
- 可空字段:某些地址字段可能为null;在连接之前将其删除。
- 去重:搜索端点可能会在地址更改时返回重复的所有者;根据您维护的稳定键(例如,名称+您关心的序列号的组合)进行去重。
可用性检查的实用模式
当您需要每个类别的通过/不通过决策时,调用商标可用性并使用:
- available: 关键字整体的“是”或“否”。
- available_classes: 商标仍然可用的类别列表。
- unavailable_classes: 存在冲突的类别列表。
- serial_numbers: 与冲突注册或申请相关的序列号,用于审计或UI链接。
典型流程:
- 从表单或CI变量接受输入关键字。
- 调用商标可用性并读取可用和类别数组。
- 如果目标类别与unavailable_classes之间存在重叠,则阻止或警告;否则允许保留并持久化带时间戳的决策。
- 可选地,跟进商标搜索以收集状态和所有者信息以供驳回/上诉UI使用。
节省时间的响应处理技巧
- 响应形状:搜索返回一个根对象,包含计数和项目;商标可用性返回一个包含关键字、可用标志、类别数组和序列号的列表;商标搜索返回计数和项目,包含详细字段,如status_label和所有者。
- 缓存:如果您的UI允许,按标准化关键字进行短时间缓存,以减少在单个会话中的重复检查。当用户编辑商标时使其失效。
- 审计:存储来自可用性检查的序列号,以便将来审核时可以准确引用在决策时导致冲突的申请。
构建生产用例
- 产品命名门槛:在PRD审查期间,运行候选名称的可用性;如果可用性为“否”或目标类别与unavailable_classes相交,则在设计提交之前要求重命名。
- 市场列表审核:在卖家或商店创建时,验证提议的商店名称;如果出现冲突,呈现拒绝原因,包括前几个序列号以演示冲突。
- 域名侧分类:将您的域名可用性逻辑与商标可用性结合。如果域名是免费的,但商标在您的操作类别中被占用,则阻止并建议替代方案。
- CI检查:在单一代码库中,解析对品牌资产的更改,提取显示的名称,并在GitHub操作中调用可用性,以便在存在冲突时使构建失败。
通过MCP从AI代理调用API
如果您从Claude Code、Cursor或Windsurf等开发者工具协调检查,您可以通过Zyla的MCP兼容端点调用相同的Hub端点。配置您的客户端以访问MCP服务,并根据您的客户端的MCP配置提供API密钥。代理将使用您的Authorization头调用上面记录的Hub URL,因此您的代码和代理工作流程保持一致。
测试和操作考虑事项
- 标准化:在您的UI和缓存键中标准化关键字(大小写、重音、标点),以便用户在切换大小写时不会得到不一致的答案。
- 所有者重复:当历史地址存在时,搜索结果中可能会出现重复;在您的视图层中去重。
- 延迟预算:前端检查应使用短客户端超时和乐观UI模式;后端批量筛选可以容纳更长的超时。
- 配额:商标搜索API使用订阅+配额,而不是按调用计费。请从7天试用或50个请求开始,然后根据需要在API页面上调整您的计划。
参考:端点摘要
- 搜索(GET): https://zylalabs.com/api/1495/trademark-search-api/1236/search
- 商标可用性(GET): https://zylalabs.com/api/1495/trademark-search-api/1237/trademark-availability
- 商标搜索(GET): https://zylalabs.com/api/1495/trademark-search-api/1238/trademark-search
所有端点都需要Authorization: Bearer YOUR_API_KEY头。仅上述字段和URL已记录;如果您需要其他过滤器或参数,请查看市场页面以获取更新。
常见问题
我如何进行身份验证?
在每个请求头中包含Authorization: Bearer YOUR_API_KEY到Hub URL。
我可以在请求中按类别或管辖区进行过滤吗?
上述公共列表未记录这些示例的请求参数。使用商标可用性响应的available_classes和unavailable_classes来决定每个类别的操作,并查看API的市场页面以获取参数更新。
哪些字段告诉我商标是“活”的还是“死”的?
使用商标搜索端点并读取响应中的status_label、status_code和status_definition。列表中提到了一种“活动”的搜索类型,排除了死商标;请查阅API页面以获取具体信息。
是否存在重复所有者?
是的。搜索端点可能会返回重复的所有者条目,特别是当所有者更改地址时。根据您的业务逻辑进行去重。
定价模型是什么?
Zyla API使用订阅+配额,而不是按调用计费。对于此API,您可以从7天试用或50个请求开始。请查看市场页面以获取当前计划和限制。
准备将其集成到您的应用程序中并发布吗?获取您的密钥并在商标搜索API上开始7天试用。一个账户解锁Zyla API Hub上成千上万的API,使用相同的密钥和订阅模型。