导航

HEAS Data Platform · 材料科学计算数据库

API 端点

RESTful API v1 · 所有数据均可程序化获取

概述

HEAS Data Platform 提供 RESTful API，可通过程序化方式访问平台的全部材料数据。所有端点均以 JSON 格式返回，这些公共 API 端点，均无需 API KEY 或认证。在请求和执行时，系统会记录 API 请求日志，这些日志将帮助我们进行错误排查、安全监测与服务运维等。并且相关数据将在合理范围内与本项目的所有合作机构共享。
速率限制：同一 IP 每 60 秒最多可发起 60 次请求；超出后，该 IP 将在 5 分钟内发出的请求将不会被系统执行。

协议
HTTPS
响应格式
application/json
认证
Public
GET /api/v1/materials

获取材料列表，支持分页、筛选和排序。

查询参数

参数 类型 默认 说明
pageint1页码
per_pageint20每页数量 (1-100)
typestring-类型筛选: HEA、TRA 或 ELA
qstring-关键词搜索 (化学式或 MP-ID)。仅支持字母、数字、括号 ()、- . , 与空格；中文等特殊字符会被忽略
crystal_systemstring-晶系: Cubic, Tetragonal, ...
is_stablebool-稳定性: true/false
min_energyfloat-最小形成能 (eV/atom)
max_energyfloat-最大形成能 (eV/atom)
elementsstring-元素筛选，精确匹配元素组成（逗号分隔标准元素符号，如 Fe,Cr；大小写不敏感，最多 10 个）。按化学式中真实存在的元素判断，Si 不会匹配 CsI
sortstring-排序字段, 前缀 - 降序

元素筛选说明

规则 说明
匹配方式 按化学式解析后的真实元素集合精确匹配，而非子串匹配：Si 只匹配含硅材料，不会误匹配 CsI；C 也不会匹配 NaCl
分隔符 支持 ,、空格、;、、，大小写不敏感（fe,cr 等价于 Fe,Cr）
容错 非元素符号会被忽略，最多 10 个元素
推荐用法 查询页提供元素周期表点选，推荐用其构造条件
请求示例 
curl "https://heas.labs.gt.ac.cn/api/v1/materials?type=HEA&per_page=5&sort=-formation_energy_per_atom"
响应示例 

{
  "success": true,
  "data": {
    "items": [
      {
        "mp_id": "mp-1097563",
        "type": "HEA",
        "formula": "TaReW2",
        "crystal_system": "Orthorhombic",
        "space_group": "Immm",
        "formation_energy_per_atom": 5.28536,
        "is_stable": false,
        "density": 1.56479,
        "nelements": 3
      },
      {
        "mp_id": "mp-1096421",
        "type": "HEA",
        "formula": "TaNbW2",
        "crystal_system": "Orthorhombic",
        "space_group": "Immm",
        "formation_energy_per_atom": 5.21092,
        "is_stable": false,
        "density": 1.35475,
        "nelements": 3
      },
      {
        "mp_id": "mp-1097618",
        "type": "HEA",
        "formula": "TaMoW2",
        "crystal_system": "Orthorhombic",
        "space_group": "Immm",
        "formation_energy_per_atom": 5.17566,
        "is_stable": false,
        "density": 1.35422,
        "nelements": 3
      },
      {
        "mp_id": "mp-1096654",
        "type": "HEA",
        "formula": "VReW2",
        "crystal_system": "Orthorhombic",
        "space_group": "Immm",
        "formation_energy_per_atom": 5.13542,
        "is_stable": false,
        "density": 1.23446,
        "nelements": 3
      },
      {
        "mp_id": "mp-1097495",
        "type": "HEA",
        "formula": "ReMoW2",
        "crystal_system": "Orthorhombic",
        "space_group": "Immm",
        "formation_energy_per_atom": 5.09028,
        "is_stable": false,
        "density": 1.39695,
        "nelements": 3
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 5,
      "total_items": 150100,
      "total_pages": 30020
    }
  },
  "meta": {
    "query_time_ms": 30.56,
    "cached": false,
    "source": "sqlite_index"
  }
}
在线试一试
GET /api/v1/materials/:id

获取单个材料的完整详情，包括基础信息、弹性、电子、磁性属性及引用。

路径参数

参数 类型 说明
idstring材料 ID (如 mp-2866)，格式: mp- 前缀 + 数字
请求示例 
curl "https://heas.labs.gt.ac.cn/api/v1/materials/mp-2866"
响应示例 

{
  "success": true,
  "data": {
    "mp_id": "mp-2866",
    "type": "HEA",
    "summary": {
      "formula": "Yb(FeSi)2",
      "mp_id": "mp-2866",
      "nelements": 3,
      "is_stable": false,
      "nsites": 5,
      "density": 7.92825,
      "volume": 71.40033,
      "a": 5.41767,
      "b": 5.41767,
      "c": 5.41767,
      "alpha": 137.62961,
      "beta": 137.62961,
      "gamma": 61.47074,
      "space_group": "I4/mmm",
      "space_group_num": 139,
      "crystal_system": "Tetragonal",
      "formation_energy_per_atom": -0.50214,
      "energy_per_atom": -17.08288,
      "energy_above_hull": 0.00216,
      "point_group": "4/mmm",
      "Bravais_Lattice": "tI",
      "Bravais_Combination": "tI",
      "packing_fraction": null,
      "uncorrected_energy_per_atom": -17.08288,
      "volume_per_atom": 14.28007,
      "c_over_a": 1,
      "b_over_a": 1,
      "poisson_ratio": 0.25211,
      "Is_FCC": 0,
      "Is_BCC": 0,
      "Is_HCP": 0
    },
    "elasticity": {
      "k_vrh": 119.518,
      "g_vrh": 70.986,
      "E_Calc(GPa)": 177.764,
      "homogeneous_poisson": 0.25211,
      "Vickers_Hard_Est(GPa)": null,
      "universal_anisotropy": 0.058,
      "Lame_Lambda(GPa)": 72.194,
      "Pugh_Ratio(K/G)": 1.68368410672527,
      "Ductility": "Ductile",
      "bulk_modulus": 119.518,
      "shear_modulus": 70.986,
      "debye_temperature": 516.2,
      "sound_velocity": 3322.8,
      "homogeneity": 0.252
    },
    "electronic": {
      "is_metal": true,
      "band_gap": 0,
      "is_gap_direct": false,
      "cbm": null
    },
    "magnetic": {
      "is_magnetic": false,
      "total_magnetization": 0.0019,
      "ordering": "NM",
      "num_magnetic_sites": 0,
      "total_mag_norm_vol": 0.00003
    },
    "refs": {
      "mp_url": "https://materialsproject.org/materials/mp-2866",
      "mp_task_ids": [
        "aaadmivi",
        "aaaeukef",
        "aaafawbu",
        "aaafbyfu",
        "aaahbakp"
      ]
    },
    "xrd": {
      "by_target": {
        "CuKa": {
          "radiation": "Cu Kα",
          "wavelength": 1.5418,
          "n_peaks": 28,
          "three_strong": [21.18, 44.52, 64.79]
        }
      }
    }
  }
}

详情接口会在 xrd 字段中嵌入该材料的 XRD 三强峰值，按靶材（辐射源）组织为 by_target 结构（含 radiation、wavelength、n_peaks 与 three_strong）。完整衍射峰列表与原始 xy 数据请见 XRD 衍射匹配 文档。

详情接口仅发布公开字段白名单，平台自研特征数据（features）不对外提供；ELA 数据集的 elasticity 会额外返回 bulk_modulus、shear_modulus、debye_temperature、sound_velocity、homogeneity 等弹性专属字段（HEA / TRA 中为 null）。

在线试一试 查看各属性详细说明
GET /api/v1/materials/:id/cif

获取材料的 CIF (Crystallographic Information File) 晶体结构数据。

参数 类型 默认 说明
id (path)string-材料 ID
format (query)stringjsonjson 或 raw
JSON 格式 
curl "https://heas.labs.gt.ac.cn/api/v1/materials/mp-2866/cif"
Raw 格式 
curl "https://heas.labs.gt.ac.cn/api/v1/materials/mp-2866/cif?format=raw"
在线试一试 (JSON) 在线试一试 (Raw)
GET /api/v1/stats

获取平台统计数据，包括材料总数、各类型数量及索引构建时间。

请求示例 
curl "https://heas.labs.gt.ac.cn/api/v1/stats"
在线试一试

错误处理

API 使用标准 HTTP 状态码表达请求结果，错误响应始终返回统一结构的 JSON 体，便于程序化判断与向用户展示：

错误响应结构

字段 类型 说明
successbool始终为 false
errorstring可读的错误描述

HTTP 状态码

状态码 含义
200请求成功
400请求参数无效（如 MP-ID 格式错误）
404资源未找到（材料 / CIF 不存在）
405请求方法不允许
429请求过于频繁；响应头 Retry-After 给出可重试的剩余秒数
457区域限制；当前 IP 所属地区不在允许访问范围内
503服务暂时不可用，请稍后重试

错误响应示例

400 无效的 MP-ID 格式 
{
  "success": false,
  "error": "Invalid material ID format"
}
404 材料未找到 
{
  "success": false,
  "error": "Material not found"
}
429 请求太频繁导致请求失败 
{
  "success": false,
  "error": "Rate limit exceeded; please retry after 300s. See /document/api for the rate-limit policy."
}
457 区域限制 IP 不在允许访问区域 
{
  "success": false,
  "error": "In mainland China, only Guizhou Province is permitted to request the service",
  "ip": "114.114.114.114",
  "region": {
    "country": "中国",
    "province": "江苏省",
    "city": "南京市",
    "isp": "0",
    "code": "CN"
  }
}
503 服务暂时不可用 
{
  "success": false,
  "error": "Service temporarily unavailable"
}
目录