Route providing computed thermodynamic data for a material such as formation energy and energy above hull. Corrected energy values are also available that employ the schemes discussed by [Jain *et al.*](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.84.045115) and [Wang *et al.*](https://chemrxiv.org/engage/chemrxiv/article-details/60c758d9469df42a4ef45757) See the `ThermoDoc` schema for a full list of fields returned by this route.
openapi: 3.1.0
info:
title: Materials Project Defect Tasks Materials Thermo API
description: "\nThe Materials Project API allows anyone to have direct access to current, up-to-date information from the Materials Project database in a structured way.\n\nThis allows for analysis, development of automated tools, machine learning, downloading personal copies of the Materials Project database and more on a large scale.\n\nThe API is offered with the hopes of making Materials Project data more useful to you. We want you to use our data! As such, the API is offered free-of-charge and we support several tools to help you get started.\n\n## API Key\nTo make any request to the Materials Project API, you must use an API key. Your API key is generated for you automatically upon registering with the Materials Project website and is synced with the email you used to register.\n\nRemember to keep your API key safe and to not share it with anyone you do not trust.\n\nIf you are logged in, you can always access your API key from this page or from your [dashboard](https://next-gen.materialsproject.org/dashboard).\n\nIf you intend heavy API usage, you can give us a heads up by sending a message to <heavy.api.use@materialsproject.org>. With the exception of retrieving charge densities, this is not required, but may help us if we see unusual load on our servers.\n\n## Accessing Data\nTo use the API, you have three options:\n\n1. You can use our first-party supported Python client. This is the recommend route. The `mp-api` package containing the client is pip installable.\n\n ```\n pip install mp-api\n ```\n\n The `MPRester` client can be accessed by importing from it. This will ultimately replace the legacy `MPRester` available in pymatgen.\n\n For more details on how to use this, including code examples, please see <https://next-gen.materialsproject.org/api>.\n\n2. You can demo the API interactively on this documentation page. Click the \"Authorize\" button, paste in your API key, and then click the appropriate section to try out a query.\n\n3. Since this is a REST API, and offers a fully-compliant OpenAPI specification, it's possible to use the API with many libraries in many languages and environments, including JavaScript, MATLAB, Mathematica, etc. However, we do not offer first-party support for explaining how to do this, and you will have to follow the specification yourself.\n\n"
version: 0.86.4rc5.dev1+g77c2c1315
x-logo:
url: https://raw.githubusercontent.com/materialsproject/emmet/master/emmet-api/emmet/api/core/assets/mp_logo_small.png
security:
- ApiKeyAuth: []
tags:
- name: Materials Thermo
description: Route providing computed thermodynamic data for a material such as formation energy and energy above hull. Corrected energy values are also available that employ the schemes discussed by [Jain *et al.*](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.84.045115) and [Wang *et al.*](https://chemrxiv.org/engage/chemrxiv/article-details/60c758d9469df42a4ef45757) See the `ThermoDoc` schema for a full list of fields returned by this route.
externalDocs:
description: For a more detailed description
url: https://docs.materialsproject.org/methodology/total-energies
paths:
/materials/thermo/:
get:
tags:
- Materials Thermo
summary: Get ThermoDoc documents
operationId: search_materials_thermo__get
parameters:
- name: thermo_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of thermo_id values to query on
title: Thermo Ids
description: Comma-separated list of thermo_id values to query on
- name: material_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of material_id values to query on
title: Material Ids
description: Comma-separated list of material_id values to query on
- name: thermo_types
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of thermo_type values to query on
title: Thermo Types
description: Comma-separated list of thermo_type values to query on
- name: formula
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by formula including anonymized formula or by including wild cards. A comma delimited string list of anonymous formulas or regular formulas can also be provided.
title: Formula
description: Query by formula including anonymized formula or by including wild cards. A comma delimited string list of anonymous formulas or regular formulas can also be provided.
- name: chemsys
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: A comma delimited string list of chemical systems. Wildcards for unknown elements only supported for single chemsys queries
title: Chemsys
description: A comma delimited string list of chemical systems. Wildcards for unknown elements only supported for single chemsys queries
- name: is_stable
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Whether the material is stable.
title: Is Stable
description: Whether the material is stable.
- name: nsites_max
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for maximum value of nsites
title: Nsites Max
description: Query for maximum value of nsites
- name: nsites_min
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for minimum value of nsites
title: Nsites Min
description: Query for minimum value of nsites
- name: nsites
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nsites being equal to an exact value
title: Nsites
description: Query for nsites being equal to an exact value
- name: nsites_not_eq
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nsites being not equal to an exact value
title: Nsites Not Eq
description: Query for nsites being not equal to an exact value
- name: nsites_eq_any
in: query
required: false
schema:
type: string
description: Query for nsites being any of these values. Provide a comma separated list.
title: Nsites Eq Any
description: Query for nsites being any of these values. Provide a comma separated list.
- name: nsites_neq_any
in: query
required: false
schema:
type: string
description: Query for nsites being not any of these values. Provide a comma separated list.
title: Nsites Neq Any
description: Query for nsites being not any of these values. Provide a comma separated list.
- name: nelements_max
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for maximum value of nelements
title: Nelements Max
description: Query for maximum value of nelements
- name: nelements_min
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for minimum value of nelements
title: Nelements Min
description: Query for minimum value of nelements
- name: nelements
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nelements being equal to an exact value
title: Nelements
description: Query for nelements being equal to an exact value
- name: nelements_not_eq
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nelements being not equal to an exact value
title: Nelements Not Eq
description: Query for nelements being not equal to an exact value
- name: nelements_eq_any
in: query
required: false
schema:
type: string
description: Query for nelements being any of these values. Provide a comma separated list.
title: Nelements Eq Any
description: Query for nelements being any of these values. Provide a comma separated list.
- name: nelements_neq_any
in: query
required: false
schema:
type: string
description: Query for nelements being not any of these values. Provide a comma separated list.
title: Nelements Neq Any
description: Query for nelements being not any of these values. Provide a comma separated list.
- name: volume_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of volume
title: Volume Max
description: Query for maximum value of volume
- name: volume_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of volume
title: Volume Min
description: Query for minimum value of volume
- name: density_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of density
title: Density Max
description: Query for maximum value of density
- name: density_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of density
title: Density Min
description: Query for minimum value of density
- name: density_atomic_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of density_atomic
title: Density Atomic Max
description: Query for maximum value of density_atomic
- name: density_atomic_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of density_atomic
title: Density Atomic Min
description: Query for minimum value of density_atomic
- name: uncorrected_energy_per_atom_max
in: query
required: false
schema:
type: number
description: Query for maximum value of uncorrected_energy_per_atom
title: Uncorrected Energy Per Atom Max
description: Query for maximum value of uncorrected_energy_per_atom
- name: uncorrected_energy_per_atom_min
in: query
required: false
schema:
type: number
description: Query for minimum value of uncorrected_energy_per_atom
title: Uncorrected Energy Per Atom Min
description: Query for minimum value of uncorrected_energy_per_atom
- name: energy_per_atom_max
in: query
required: false
schema:
type: number
description: Query for maximum value of energy_per_atom
title: Energy Per Atom Max
description: Query for maximum value of energy_per_atom
- name: energy_per_atom_min
in: query
required: false
schema:
type: number
description: Query for minimum value of energy_per_atom
title: Energy Per Atom Min
description: Query for minimum value of energy_per_atom
- name: energy_uncertainy_per_atom_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of energy_uncertainy_per_atom
title: Energy Uncertainy Per Atom Max
description: Query for maximum value of energy_uncertainy_per_atom
- name: energy_uncertainy_per_atom_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of energy_uncertainy_per_atom
title: Energy Uncertainy Per Atom Min
description: Query for minimum value of energy_uncertainy_per_atom
- name: formation_energy_per_atom_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of formation_energy_per_atom
title: Formation Energy Per Atom Max
description: Query for maximum value of formation_energy_per_atom
- name: formation_energy_per_atom_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of formation_energy_per_atom
title: Formation Energy Per Atom Min
description: Query for minimum value of formation_energy_per_atom
- name: energy_above_hull_max
in: query
required: false
schema:
type: number
description: Query for maximum value of energy_above_hull
title: Energy Above Hull Max
description: Query for maximum value of energy_above_hull
- name: energy_above_hull_min
in: query
required: false
schema:
type: number
description: Query for minimum value of energy_above_hull
title: Energy Above Hull Min
description: Query for minimum value of energy_above_hull
- name: equilibrium_reaction_energy_per_atom_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of equilibrium_reaction_energy_per_atom
title: Equilibrium Reaction Energy Per Atom Max
description: Query for maximum value of equilibrium_reaction_energy_per_atom
- name: equilibrium_reaction_energy_per_atom_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of equilibrium_reaction_energy_per_atom
title: Equilibrium Reaction Energy Per Atom Min
description: Query for minimum value of equilibrium_reaction_energy_per_atom
- name: decomposition_enthalpy_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of decomposition_enthalpy
title: Decomposition Enthalpy Max
description: Query for maximum value of decomposition_enthalpy
- name: decomposition_enthalpy_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of decomposition_enthalpy
title: Decomposition Enthalpy Min
description: Query for minimum value of decomposition_enthalpy
- name: _page
in: query
required: false
schema:
type: integer
description: Page number to request (takes precedent over _limit and _skip).
title: ' Page'
description: Page number to request (takes precedent over _limit and _skip).
- name: _per_page
in: query
required: false
schema:
type: integer
description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
default: 100
title: ' Per Page'
description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
- name: _skip
in: query
required: false
schema:
type: integer
description: Number of entries to skip in the search.
default: 0
title: ' Skip'
description: Number of entries to skip in the search.
- name: _limit
in: query
required: false
schema:
type: integer
description: Max number of entries to return in a single query. Limited to 1000.
default: 100
title: ' Limit'
description: Max number of entries to return in a single query. Limited to 1000.
- name: _fields
in: query
required: false
schema:
type: string
description: 'Fields to project from ThermoDoc as a list of comma separated strings. Fields include: `builder_meta` `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `material_id` `deprecated` `deprecation_reasons` `last_updated` `origins` `warnings` `structure` `property_name` `thermo_type` `thermo_id` `uncorrected_energy_per_atom` `energy_per_atom` `energy_uncertainy_per_atom` `formation_energy_per_atom` `energy_above_hull` `is_stable` `equilibrium_reaction_energy_per_atom` `decomposes_to` `decomposition_enthalpy` `decomposition_enthalpy_decomposes_to` `energy_type` `entry_types` `entries`'
title: ' Fields'
description: 'Fields to project from ThermoDoc as a list of comma separated strings. Fields include: `builder_meta` `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `material_id` `deprecated` `deprecation_reasons` `last_updated` `origins` `warnings` `structure` `property_name` `thermo_type` `thermo_id` `uncorrected_energy_per_atom` `energy_per_atom` `energy_uncertainy_per_atom` `formation_energy_per_atom` `energy_above_hull` `is_stable` `equilibrium_reaction_energy_per_atom` `decomposes_to` `decomposition_enthalpy` `decomposition_enthalpy_decomposes_to` `energy_type` `entry_types` `entries`'
- name: _all_fields
in: query
required: false
schema:
type: boolean
description: Include all fields.
default: false
title: ' All Fields'
description: Include all fields.
- name: license
in: query
required: false
schema:
anyOf:
- enum:
- BY-C
- BY-NC
- All
type: string
- type: 'null'
description: Query by license. Can be commercial or non-commercial, or both
default: BY-C
title: License
description: Query by license. Can be commercial or non-commercial, or both
responses:
'200':
description: Search for a ThermoDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_ThermoDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
EmmetMeta:
properties:
emmet_version:
anyOf:
- type: string
- type: 'null'
title: Emmet Version
description: The version of emmet this document was built with.
default: 0.86.4rc4
pymatgen_version:
anyOf:
- type: string
- type: 'null'
title: Pymatgen Version
description: The version of pymatgen this document was built with.
default: 2026.4.16
run_id:
anyOf:
- type: string
- type: 'null'
title: Run Id
description: The run id associated with this data build.
batch_id:
anyOf:
- type: string
- type: 'null'
title: Batch Id
description: Identifier corresponding to the origin of this document's blessed task.
database_version:
anyOf:
- type: string
- type: 'null'
title: Database Version
description: The database version for the built data.
build_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Build Date
description: The build date for this document.
license:
anyOf:
- type: string
enum:
- BY-C
- BY-NC
- type: 'null'
title: License
description: License for the data entry.
type: object
title: EmmetMeta
description: Default emmet metadata.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
Response_ThermoDoc_:
properties:
data:
anyOf:
- items:
$ref: '#/components/schemas/ThermoDoc'
type: array
- type: 'null'
title: Data
description: List of returned data
errors:
anyOf:
- items:
$ref: '#/components/schemas/Error'
type: array
- type: 'null'
title: Errors
description: Any errors on processing this query
meta:
anyOf:
- $ref: '#/components/schemas/Meta'
- type: 'null'
description: Extra information for the query
type: object
title: Response[ThermoDoc]
ThermoDoc:
properties:
builder_meta:
anyOf:
- $ref: '#/components/schemas/EmmetMeta'
- type: 'null'
description: Builder metadata.
nsites:
anyOf:
- type: integer
- type: 'null'
title: Nsites
description: Total number of sites in the structure.
elements:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Elements
description: List of elements in the material.
nelements:
anyOf:
- type: integer
- type: 'null'
title: Nelements
description: Number of elements.
composition:
anyOf:
- additionalProperties:
type: number
type: object
- type: 'null'
title: Composition
description: Full composition for the material.
composition_reduced:
anyOf:
- additionalProperties:
type: number
type: object
- type: 'null'
title: Reduced Composition
description: Simplified representation of the composition.
formula_pretty:
anyOf:
- type: string
- type: 'null'
title: Pretty Formula
description: Cleaned representation of the formula.
formula_anonymous:
anyOf:
- type: string
- type: 'null'
title: Anonymous Formula
description: Anonymized representation of the formula.
chemsys:
anyOf:
- type: string
- type: 'null'
title: Chemical System
description: Dash-separated string of elements in the material.
volume:
anyOf:
- type: number
- type: 'null'
title: Volume
description: Total volume for this structure in ų.
density:
anyOf:
- type: number
- type: 'null'
title: Density
description: Density in g/cm³.
density_atomic:
anyOf:
- type: number
- type: 'null'
title: Packing Density
description: The atomic packing density in ų/atom.
symmetry:
anyOf:
- $ref: '#/components/schemas/SymmetryData'
- type: 'null'
description: Symmetry data for this material.
material_id:
anyOf:
- type: string
pattern: ^([A-Za-z]+-)?(\d+)(-[A-Za-z0-9]+)*$
examples:
- mp-3534
- '3453'
- mp-834-Ag
- type: string
examples:
- mp-ft
- task:pqrs
- type: 'null'
title: Material Id
description: 'The Materials Project ID of the material, used as a universal reference across property documents.This comes in the form: mp-******.'
deprecated:
type: boolean
title: Deprecated
description: Whether this property document is deprecated.
default: true
deprecation_reasons:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Deprecation Reasons
description: List of deprecation tags detailing why this document isn't valid.
last_updated:
type: string
format: date-time
title: Last Updated
description: Timestamp for the most recent calculation update for this property.
origins:
anyOf:
- items:
$ref: '#/components/schemas/PropertyOrigin'
type: array
- type: 'null'
title: Origins
description: Dictionary for tracking the provenance of properties.
warnings:
items:
type: string
type: array
title: Warnings
description: Any warnings related to this property.
default: []
property_name:
type: string
title: Property Name
default: thermo
thermo_type:
type: string
title: Thermo Type
description: Functional types of calculations involved in the energy mixing scheme.
thermo_id:
type: string
description: Unique document ID which is composed of the Material ID and thermo data type.
uncorrected_energy_per_atom:
type: number
title: Uncorrected Energy Per Atom
description: The total DFT energy of this material per atom in eV/atom.
energy_per_atom:
type: number
title: Energy Per Atom
description: The total corrected DFT energy of this material per atom in eV/atom.
energy_uncertainy_per_atom:
anyOf:
- type: number
- type: 'null'
title: Energy Uncertainy Per Atom
description: ''
formation_energy_per_atom:
anyOf:
- type: number
- type: 'null'
title: Formation Energy Per Atom
description: The formation energy per atom in eV/atom.
energy_above_hull:
type: number
title: Energy Above Hull
description: The energy above the hull in eV/Atom.
is_stable:
type: boolean
title: Is Stable
description: Flag for whether this material is on the hull and therefore stable.
default: false
equilibrium_reaction_energy_per_atom:
anyOf:
- type: number
- type: 'null'
title: Equilibrium Reaction Energy Per Atom
description: The reaction energy of a stable entry from the neighboring equilibrium stable materials in eV. Also known as the inverse distance to hull.
decomposes_to:
anyOf:
- items:
$ref: '#/components/schemas/DecompositionProduct'
type: array
- type: 'null'
title: Decomposes To
description: List of decomposition data for this material. Only valid for metastable or unstable material.
decomposition_enthalpy:
anyOf:
- type: number
- type: 'null'
title: Decomposition Enthalpy
description: Decomposition enthalpy as defined by `get_decomp_and_phase_separation_energy` in pymatgen.
decomposition_enthalpy_decomposes_to:
anyOf:
- items:
$ref: '#/components/schemas/DecompositionProduct'
type: array
- type: 'null'
title: Decomposition Enthalpy Decomposes To
description: List of decomposition data associated with the decomposition_enthalpy quantity.
energy_type:
type: string
title: Energy Type
description: The type of calculation this energy evaluation comes from.
entry_types:
items:
type: string
type: array
title: Entry Types
description: List of available energy types computed for this material.
entries:
additionalProperties:
additionalProperties: true
type: object
type: object
title: Entries
description: List of all entries that are valid for this material. The keys for this dictionary are names of various calculation types.
type: object
required:
- thermo_type
- thermo_id
- uncorrected_energy_per_atom
- energy_per_atom
- energy_above_hull
- energy_type
- entry_types
- entries
title: ThermoDoc
description: A thermo entry document
Meta:
properties:
api_version:
type: string
title: Api Version
description: A string containing the version of the Materials API implementation, e.g. v0.9.5
default: 0.86.4rc5.dev1+g77c2c1315
time_stamp:
type: string
format: date-time
title: Time Stamp
description: A string containing the date and time at which the query was executed
total_doc:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: Total Doc
description: The total number of documents available for this query
facet:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Facet
description: A dictionary containing the facets available for this query
additionalProperties: true
type: object
title: Meta
description: Meta information for the MAPI Response.
SymmetryData:
properties:
crystal_system:
anyOf:
- type: string
- type: 'null'
title: Crystal System
description: The crystal system for this lattice.
symbol:
anyOf:
- type: string
- type: 'null'
title: Space Group Symbol
description: The spacegroup symbol for the lattice.
hall:
anyOf:
- type: string
- type: 'null'
title: Hall Symbol
description: Hall symbol for the lattice
number:
anyOf:
- type: integer
- type: 'null'
title: Space Group Number
description: The spacegroup number for the lattice.
point_group:
anyOf:
- ty
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/materials-project/refs/heads/main/openapi/materials-project-materials-thermo-api-openapi.yml