# 商标检索 (/docs/search)

**一个端点覆盖精确查询与相似度筛查：`POST /v1/trademarks/search`。** 检索 10 点/页，相似度计算另计 10 点/项。

## 基础检索 [#基础检索]

```bash
curl https://api.lagrange.so/v1/trademarks/search \
  -H "Authorization: Bearer $LGR_KEY" \
  -d '{ "q": "NOVA", "offices": ["US"], "limit": 20 }'
```

## 相似度筛查（排查场景） [#相似度筛查排查场景]

加 `similarity` 参数即启用五通道并行筛查，每条命中带解释：

```json
{
  "q": "KOMM",
  "offices": ["US", "EM"],
  "similarity": ["identical", "fuzzy", "embedded", "phonetic"]
}
```

```json
{
  "results": [
    { "mark_text": "KOMMI",  "similarity": { "tier": "near_identical", "via": "fuzzy", "score": 0.94 } },
    { "mark_text": "KOMMEL", "similarity": { "tier": "similar",       "via": "fuzzy", "score": 0.81 } }
  ]
}
```

- `tier`：风险分级（`identical` > `near_identical` > `similar` > `weak`）
- `via`：命中通道，用于解释为什么命中
- 长公共前缀有加权：`LAGRANGE` vs `LAGRANGIAN` 编辑距离 3，仍判 `near_identical`

## 过滤参数 [#过滤参数]

| 参数 | 类型 | 说明 |
|---|---|---|
| `q` | string | 商标名或申请人关键词 |
| `offices` | string[] | 法域过滤，缺省为全部 |
| `nice_classes` | int[] | 尼斯分类 |
| `status.stage` | string | `live` / `pending` / `dead` |
| `similarity` | string[] | 启用哪些相似度通道 |
| `limit` / `page` | int | 每页 ≤ 100，默认 20 |

<Callout type="info" title="枚举不全列">

完整法域代码、状态枚举与事件字典走参考端点（0 点）：`/v1/offices`、`/v1/status-codes`、`/v1/event-types`。

</Callout>

<Callout type="warning" title="已知限制">

- lookalike（视觉相似）通道在内测中，尚未默认开启
- 单次检索窗口上限 10,000 行，深翻页请加过滤条件
- 不翻译：`mark_text` 存多语原文，请按原文检索

</Callout>