API Endpoints - HEAS Data Platform - Materials Science Database

Overview

The HEAS Data Platform provides a RESTful API for programmatic access to all platform material data. All endpoints return JSON; these public API endpoints require no API KEY or authentication. When requests are made and processed, the system logs API requests; these logs help us with error troubleshooting, security monitoring and service operations. Related data will also be shared, within a reasonable scope, with all partner institutions of this project.
Rate limit: the same IP may make at most 60 requests per 60 seconds; beyond that, requests from that IP will not be executed for 5 minutes.

Protocol

HTTPS

Response Format

application/json

Authentication

Public

GET /api/v1/materials

Fetch the material list, with pagination, filtering and sorting support.

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	20	Records per page (1-100)
type	string	-	Type filter: `HEA`, `TRA` or `ELA`
q	string	-	Keyword search (chemical formula or MP-ID). Only letters, digits, parentheses `()`, `-` `.` `,` and spaces are supported; special characters such as Chinese are ignored
crystal_system	string	-	Crystal system: Cubic, Tetragonal, ...
is_stable	bool	-	Stability: `true`/`false`
min_energy	float	-	Minimum formation energy (eV/atom)
max_energy	float	-	Maximum formation energy (eV/atom)
elements	string	-	Element filter, exact match on the element composition (comma-separated standard element symbols, e.g. `Fe,Cr`; case-insensitive, at most 10). Matched against the elements actually present in the chemical formula, so `Si` does not match `CsI`
sort	string	-	Sort field, with the `-` prefix for descending order

Element Filter Notes

Rule	Description
Match mode	Exact match on the real element set parsed from the chemical formula, not substring matching: Si only matches silicon-containing materials and will not mistakenly match CsI; C also will not match NaCl
Separators	Supports ,, spaces, ;, 、; case-insensitive (fe,cr is equivalent to Fe,Cr)
Fault tolerance	Non-element symbols are ignored; at most 10 elements
Recommended usage	The query page provides a periodic-table picker; using it to build conditions is recommended

Request example

curl "https://heas.labs.gt.ac.cn/api/v1/materials?type=HEA&per_page=5&sort=-formation_energy_per_atom"

Response example


{
  "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"
  }
}

Try it online

GET /api/v1/materials/:id

Fetch the full details of a single material, including basic information, elasticity, electronic and magnetic properties, and references.

Path Parameters

Parameter	Type	Description
id	string	Material ID (e.g. `mp-2866`), format: `mp-` prefix + digits

Request example

curl "https://heas.labs.gt.ac.cn/api/v1/materials/mp-2866"

Response example


{
  "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]
        }
      }
    }
  }
}

The detail endpoint embeds the material's XRD three-strongest peak values in the xrd field, organized by target (radiation) as a by_target structure (including radiation, wavelength, n_peaks and three_strong). For the full diffraction peak list and raw xy data, see the XRD Diffraction Matching documentation.

The detail endpoint publishes only a public-field whitelist; the platform's self-developed feature data (features) is not exposed. The elasticity block of the ELA dataset additionally returns bulk_modulus, shear_modulus, debye_temperature, sound_velocity, homogeneity and other elasticity-specific fields (null in HEA / TRA).

Try it online View detailed property descriptions

GET /api/v1/materials/:id/cif

Fetch the material's CIF (Crystallographic Information File) crystal-structure data.

Parameter	Type	Default	Description
id (path)	string	-	Material ID
format (query)	string	json	`json` or `raw`

JSON format

curl "https://heas.labs.gt.ac.cn/api/v1/materials/mp-2866/cif"

Raw format

curl "https://heas.labs.gt.ac.cn/api/v1/materials/mp-2866/cif?format=raw"

Try it online (JSON) Try it online (Raw)

GET /api/v1/search

Quickly search materials, matching chemical formula or MP-ID. Returns a lightweight result list, suitable for autocomplete scenarios. When q itself is a single element symbol (e.g. Fe, si), matching is by exact element.

Parameter	Type	Default	Description
q	string	-	Search keyword (required)
type	string	-	Type: `HEA`, `TRA` or `ELA`
limit	int	10	Number of results (1-50)

Request example

curl "https://heas.labs.gt.ac.cn/api/v1/search?q=Fe&type=HEA&limit=5"

Try it online

GET /api/v1/stats

Fetch platform statistics, including the total material count, per-type counts and index build time.

Request example

curl "https://heas.labs.gt.ac.cn/api/v1/stats"

Try it online

Error Handling

The API uses standard HTTP status codes to express request results; error responses always return a uniformly structured JSON body for programmatic judgment and user display:

Error Response Structure

Field	Type	Description
success	bool	Always `false`
error	string	Human-readable error description

HTTP Status Codes

Status Code	Meaning
200	Request succeeded
400	Invalid request parameters (e.g. malformed MP-ID)
404	Resource not found (material / CIF does not exist)
405	Request method not allowed
429	Too many requests; the `Retry-After` response header gives the remaining seconds before retrying
457	Region restriction; the current IP's region is outside the allowed access range
503	Service temporarily unavailable; please retry later

Example Error Responses

400 Invalid MP-ID format

{
  "success": false,
  "error": "Invalid material ID format"
}

404 Material not found

{
  "success": false,
  "error": "Material not found"
}

429 Request failed due to too many requests

{
  "success": false,
  "error": "Rate limit exceeded; please retry after 300s. See /document/api for the rate-limit policy."
}

457 Region restriction: IP not in the allowed region

{
  "success": false,
  "error": "In mainland China, only Guizhou Province is permitted to request the service",
  "ip": "114.114.114.114",
  "region": {
    "country": "China",
    "province": "Jiangsu",
    "city": "Nanjing",
    "isp": "0",
    "code": "CN"
  }
}

503 Service temporarily unavailable

{
  "success": false,
  "error": "Service temporarily unavailable"
}