物质检索

通过名称、CAS、SMILES、分子式、结构相似性或子结构条件检索化学物质，并返回标准标识、基础物性、供应信息和安全数据索引。

接口说明

物质检索接口适合接入企业内部检索系统、ELN/LIMS、采购系统和研发知识库。接口采用 JSON 请求体，支持分页、多条件组合和字段级检索。

接口名称: 物质检索

计费方式: 按调用次数计费

返回格式: JSON

适用场景: 分子检索、物质标准化、供应信息查询

快速入门

向慧化团队申请企业应用，获取 client_id 和 client_secret。
在服务端生成访问令牌，并在请求头中携带 Authorization: Bearer token。
按接口字段构造检索条件，使用 POST 提交 JSON 请求体。

鉴权方式

所有 API 请求均需通过企业应用令牌鉴权。令牌应在服务端保存，不建议暴露在浏览器、客户端或公开仓库中。

Authorization: Bearer <access_token>
Content-Type: application/json

接口地址

POSThttps://openapi.insightchemy.com/v1/chem/search

请求参数

全局请求参数详见公共参数。本接口请求体参数如下：

名称	类型	必填	说明
pagination	object	是	分页参数
- offset	int64	是	偏移量，从 0 开始
- limit	int64	是	获取条数，建议不超过 100
search	array<object>	是	检索条件数组
- logic_symbol	enum	是	条件逻辑，取值见条件逻辑
- filter	object	是	条件内容
- - field	enum	是	检索字段，取值见检索字段
- - value	object	是	检索值，根据 field 决定必填字段
- - - str	string	否	字符串检索值，适用于名称、CAS、SMILES 等字段
- - - multi_str	array<string>	否	字符串数组检索值
- - - range	object	否	数值范围检索值
- - - min	string	否	最小值，空字符串表示不限制
- - - max	string	否	最大值，空字符串表示不限制
options	object	否	返回内容控制
- include_supplier	boolean	否	是否返回供应信息，默认 false
- include_safety	boolean	否	是否返回安全信息索引，默认 false
- include_properties	boolean	否	是否返回基础物化性质，默认 true

返回参数

名称	类型	说明
code	string	返回码，`0` 表示正常返回
message	string	返回信息
data	object	返回数据
- total	int64	命中总数
- items	array<object>	物质记录列表
- - substance_id	string	慧化物质 ID
- - name	string	中文或英文标准名称
- - cas	string	CAS 号
- - smiles	string	标准化 SMILES
- - formula	string	分子式
- - molecular_weight	number	分子量
- - properties	object	基础物化性质
- - suppliers	array<object>	供应信息列表，仅在 include_supplier 为 true 时返回
- - safety	object	SDS 和安全信息索引，仅在 include_safety 为 true 时返回

请求示例

{
  "pagination": {
    "offset": 0,
    "limit": 10
  },
  "search": [
    {
      "logic_symbol": "AND",
      "filter": {
        "field": "CAS",
        "value": {
          "str": "50-78-2"
        }
      }
    }
  ],
  "options": {
    "include_supplier": true,
    "include_safety": true,
    "include_properties": true
  }
}

返回示例

正常返回

{
  "code": "0",
  "message": "success",
  "data": {
    "total": 1,
    "items": [
      {
        "substance_id": "HH-CHEM-000050782",
        "name": "阿司匹林",
        "cas": "50-78-2",
        "smiles": "CC(=O)Oc1ccccc1C(=O)O",
        "formula": "C9H8O4",
        "molecular_weight": 180.16,
        "properties": {
          "melting_point": "135-136 °C",
          "boiling_point": "",
          "density": "1.40 g/cm3"
        },
        "suppliers": [
          {
            "name": "示例供应商",
            "product_url": "https://example.com/product/50-78-2"
          }
        ],
        "safety": {
          "sds_available": true,
          "ghs_signal_word": "Warning"
        }
      }
    ]
  }
}

错误返回

{
  "code": "40001",
  "message": "invalid request parameter: search[0].filter.field",
  "data": null
}

错误码

错误码	说明	处理建议
40001	请求参数错误	检查字段名称、类型和必填参数
40101	鉴权失败	检查访问令牌是否有效
40301	接口权限不足	确认企业应用是否开通该接口
42901	调用频率超限	降低并发请求或申请更高额度
50001	服务内部错误	稍后重试或联系慧化技术支持

枚举值

条件逻辑

值	说明
AND	当前条件与上一条件同时满足
OR	当前条件与上一条件满足其一

检索字段

值	说明
NAME	物质名称
CAS	CAS 号
SMILES	SMILES 表达式
FORMULA	分子式
SUBSTRUCTURE	子结构检索
SIMILARITY	结构相似性检索
MOLECULAR_WEIGHT	分子量范围

公共参数

名称	位置	必填	说明
Authorization	Header	是	访问令牌，格式为 Bearer token
Content-Type	Header	是	固定为 application/json
X-Request-Id	Header	否	请求追踪 ID，建议由调用方生成
locale	Body	否	返回语言，支持 zh-CN / en-US

注意事项

结构检索类字段建议使用标准化 SMILES，避免盐型、同位素和电荷表达差异造成召回不稳定。
批量检索时建议拆分为多次请求，避免单次请求体过大影响响应时间。
供应信息、SDS 和部分计算性质可能存在数据授权限制，具体返回范围以企业开通权限为准。