导航

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

API 端点

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

概述

HEAS Data Platform 提供 RESTful API，允许你以程序化方式访问所有材料数据。所有端点均返回 JSON 格式数据，无需 API Key 或认证。

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

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

查询参数

参数 类型 默认 说明
pageint1页码
per_pageint20每页数量 (1-100)
typestring-类型筛选: HEA 或 TRA
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-100",
        "type": "HEA",
        "formula": "Fe100Cr",
        "crystal_system": "",
        "space_group": "",
        "formation_energy_per_atom": null,
        "is_stable": false,
        "density": null,
        "nelements": 0
      },
      {
        "mp_id": "mp-101",
        "type": "HEA",
        "formula": "Fe101Cr",
        "crystal_system": "",
        "space_group": "",
        "formation_energy_per_atom": null,
        "is_stable": false,
        "density": null,
        "nelements": 0
      },
      {
        "mp_id": "mp-102",
        "type": "HEA",
        "formula": "Fe102Cr",
        "crystal_system": "",
        "space_group": "",
        "formation_energy_per_atom": null,
        "is_stable": false,
        "density": null,
        "nelements": 0
      },
      {
        "mp_id": "mp-103",
        "type": "HEA",
        "formula": "Fe103Cr",
        "crystal_system": "",
        "space_group": "",
        "formation_energy_per_atom": null,
        "is_stable": false,
        "density": null,
        "nelements": 0
      },
      {
        "mp_id": "mp-104",
        "type": "HEA",
        "formula": "Fe104Cr",
        "crystal_system": "",
        "space_group": "",
        "formation_energy_per_atom": null,
        "is_stable": false,
        "density": null,
        "nelements": 0
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total_items": 5,
      "total_pages": 1
    }
  },
  "meta": {
    "query_time_ms": 0.8,
    "cached": true
  }
}
在线试一试
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": {
      "mp_id": "mp-2866",
      "formula": "Yb(FeSi)2",
      "nelements": 3,
      "nsites": 5,
      "density": 7.92825,
      "volume": 71.40033,
      "energy_above_hull": 0.00216,
      "formation_energy_per_atom": -0.50214,
      "energy_per_atom": -17.08288,
      "is_stable": false,
      "uncorrected_energy_per_atom": -17.08288,
      "last_updated": "2025-09-23 22:45:43.837000+00:00",
      "deprecated": false,
      "possible_species": [
        "Fe3+",
        "Yb2+",
        "Si4-"
      ],
      "crystal_system": "Tetragonal",
      "space_group": "I4/mmm",
      "space_group_num": 139,
      "point_group": "4/mmm",
      "a": 5.41767,
      "b": 5.41767,
      "c": 5.41767,
      "alpha": 137.6296,
      "beta": 137.6296,
      "gamma": 61.4707,
      "volume_cell": 71.40033,
      "volume_per_atom": 14.28007,
      "c_over_a": 1,
      "b_over_a": 1,
      "Bravais_Lattice": "tI",
      "Lattice_Type_Detail": "Body-Centered Tetragonal",
      "Lattice_Centering": "Body-Centered",
      "Bravais_Combination": "tI",
      "Is_FCC": false,
      "Is_BCC": false,
      "Is_HCP": false,
      "Is_Bravais_aP": false,
      "Is_Bravais_mP": false,
      "Is_Bravais_mC": false,
      "Is_Bravais_oP": false,
      "Is_Bravais_oC": false,
      "Is_Bravais_oI": false,
      "Is_Bravais_oF": false,
      "Is_Bravais_tP": false,
      "Is_Bravais_tI": true,
      "Is_Bravais_hP": false,
      "Is_Bravais_hR": false,
      "Is_Bravais_cP": false,
      "Is_Bravais_cI": false,
      "Is_Bravais_cF": false,
      "packing_fraction": null
    },
    "elasticity": {
      "k_vrh": 119.518,
      "g_vrh": 70.986,
      "k_voigt": 119.547,
      "g_voigt": 71.392,
      "k_reuss": 119.489,
      "g_reuss": 70.58,
      "poisson_ratio": null,
      "universal_anisotropy": 0.058,
      "homogeneous_poisson": 0.252,
      "E_Calc(GPa)": 177.764,
      "nu_Calc": 0.25211,
      "Lame_Lambda(GPa)": 72.194,
      "Pugh_Ratio(K/G)": 1.6837,
      "Cauchy_Pressure(GPa)": 1.208,
      "Vickers_Hard_Est(GPa)": 10.16,
      "Ductility": "Brittle",
      "Gruneisen_Approx": 1.5102
    },
    "electronic": {
      "is_metal": true,
      "band_gap": 0,
      "is_gap_direct": false,
      "cbm": null,
      "vbm": null
    },
    "magnetic": {
      "total_magnetization": 0.0019,
      "total_mag_norm_vol": 0.00003,
      "num_magnetic_sites": 0,
      "ordering": "NM",
      "is_magnetic": false
    },
    "refs": {
      "dois": [],
      "bibtex_entries": [],
      "origin_tasks": [
        "mp-3216683",
        "mp-3216683",
        "mp-3216683"
      ],
      "raw_refs": [],
      "mp_task_ids": [
        "mp-2876117",
        "mp-2866",
        "mp-1136266",
        "mp-2299798",
        "mp-2865456",
        "mp-927741",
        "mp-2318830",
        "mp-2875989",
        "mp-927308",
        "mp-2044096",
        "mp-2286124",
        "mp-2876039",
        "mp-2875923",
        "mp-1798578",
        "mp-1251770",
        "mp-1256110",
        "mp-2858143",
        "mp-2858161",
        "mp-1248556",
        "mp-3216683",
        "mp-2879983",
        "mp-1587802",
        "mp-1703469",
        "mp-1124887",
        "mp-2875945",
        "mp-1441451",
        "mp-2879967",
        "mp-2293913",
        "mp-911301",
        "mp-2186293",
        "mp-2046715",
        "mp-1953833",
        "mp-2876065",
        "mp-2865464",
        "mp-2876061"
      ],
      "mp_url": "https://next-gen.materialsproject.org/materials/mp-2866"
    }
  }
}
在线试一试 查看各属性详细说明
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 状态码表示请求结果：

状态码 含义
200请求成功
400请求参数无效 (如 MP-ID 格式错误)
404资源未找到 (材料不存在)
405请求方法不允许
错误响应示例 
{
  "success": false,
  "error": "Material not found"
}
目录
查看属性说明
属性说明