Materials Project Molecules Summary API
Route for a summary of all data calculated on 'core' molecules in the Materials Project molecules database. See the `MoleculeSummaryDoc` schema for a full list of fields returned by this route.
Route for a summary of all data calculated on 'core' molecules in the Materials Project molecules database. See the `MoleculeSummaryDoc` schema for a full list of fields returned by this route.
openapi: 3.1.0
info:
title: Materials Project Defect Tasks Molecules Summary 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: Molecules Summary
description: Route for a summary of all data calculated on 'core' molecules in the Materials Project molecules database. See the `MoleculeSummaryDoc` schema for a full list of fields returned by this route.
paths:
/molecules/summary/:
get:
tags:
- Molecules Summary
summary: Get MoleculeSummaryDoc documents
operationId: search_molecules_summary__get
parameters:
- name: molecule_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of molecule_ids to query on
title: Molecule Ids
description: Comma-separated list of molecule_ids to query on
- name: formula
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by alphabetical formula. A comma delimited string list of alphabetical formulas can also be provided.
title: Formula
description: Query by alphabetical formula. A comma delimited string list of alphabetical 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: elements
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by elements in the material composition as a comma-separated list
title: Elements
description: Query by elements in the material composition as a comma-separated list
- name: exclude_elements
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by excluded elements in the material composition as a comma-separated list
title: Exclude Elements
description: Query by excluded elements in the material composition as a comma-separated list
- name: has_props
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-delimited list of possible properties given by HasPropsEnum to search for.
title: Has Props
description: Comma-delimited list of possible properties given by HasPropsEnum to search for.
- name: charge
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query by molecular charge
title: Charge
description: Query by molecular charge
- name: spin_multiplicity
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query by molecular spin multiplicity.
title: Spin Multiplicity
description: Query by molecular spin multiplicity.
- name: inchi
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: International chemical identifier (InChI) string for this molecule
title: Inchi
description: International chemical identifier (InChI) string for this molecule
- name: inchi_key
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Hash of the InChI, also known as the InChI-key
title: Inchi Key
description: Hash of the InChI, also known as the InChI-key
- name: species_hash
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Graph hash augmented with node species
title: Species Hash
description: Graph hash augmented with node species
- name: coord_hash
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Graph hash augmented with node XYZ coordinates
title: Coord Hash
description: Graph hash augmented with node XYZ coordinates
- 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: 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: _sort_fields
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma delimited fields to sort with. Prefixing '-' to a field will force a sort in descending order.
title: ' Sort Fields'
description: Comma delimited fields to sort with. Prefixing '-' to a field will force a sort in descending order.
- name: _fields
in: query
required: false
schema:
type: string
description: 'Fields to project from MoleculeSummaryDoc as a list of comma separated strings. Fields include: `charge` `spin_multiplicity` `natoms` `elements` `nelements` `nelectrons` `composition` `composition_reduced` `formula_alphabetical` `formula_pretty` `formula_anonymous` `chemsys` `symmetry` `species_hash` `coord_hash` `property_name` `property_id` `molecule_id` `deprecated` `deprecation_reasons` `level_of_theory` `solvent` `lot_solvent` `last_updated` `origins` `warnings` `molecules` `molecule_levels_of_theory` `inchi` `inchi_key` `task_ids` `similar_molecules` `constituent_molecules` `unique_calc_types` `unique_task_types` `unique_levels_of_theory` `unique_solvents` `unique_lot_solvents` `thermo` `vibration` `orbitals` `partial_charges` `partial_spins` `bonding` `multipole_moments` `redox` `metal_binding` `has_props`'
title: ' Fields'
description: 'Fields to project from MoleculeSummaryDoc as a list of comma separated strings. Fields include: `charge` `spin_multiplicity` `natoms` `elements` `nelements` `nelectrons` `composition` `composition_reduced` `formula_alphabetical` `formula_pretty` `formula_anonymous` `chemsys` `symmetry` `species_hash` `coord_hash` `property_name` `property_id` `molecule_id` `deprecated` `deprecation_reasons` `level_of_theory` `solvent` `lot_solvent` `last_updated` `origins` `warnings` `molecules` `molecule_levels_of_theory` `inchi` `inchi_key` `task_ids` `similar_molecules` `constituent_molecules` `unique_calc_types` `unique_task_types` `unique_levels_of_theory` `unique_solvents` `unique_lot_solvents` `thermo` `vibration` `orbitals` `partial_charges` `partial_spins` `bonding` `multipole_moments` `redox` `metal_binding` `has_props`'
- name: _all_fields
in: query
required: false
schema:
type: boolean
description: Include all fields.
default: false
title: ' All Fields'
description: Include all fields.
responses:
'200':
description: Search for a MoleculeSummaryDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_MoleculeSummaryDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
TypedAggregateProperitesDict:
properties:
magmom:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Magmom
charge:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Charge
velocities:
anyOf:
- items:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Velocities
selective_dynamics:
anyOf:
- items:
prefixItems:
- type: boolean
- type: boolean
- type: boolean
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Selective Dynamics
type: object
title: TypedAggregateProperitesDict
VibrationComposite:
properties:
property_id:
anyOf:
- type: string
- type: 'null'
title: Property Id
description: Property ID for this VibrationDoc.
level_of_theory:
anyOf:
- type: string
- type: 'null'
title: Level Of Theory
description: Level of theory for this VibrationDoc.
frequencies:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Frequencies
description: List of molecular vibrational frequencies
type: object
title: VibrationComposite
description: Summary information obtained from VibrationDocs
PartialChargesComposite:
properties:
property_id:
anyOf:
- type: string
- type: 'null'
title: Property Id
description: Property ID for this PartialChargesDoc.
level_of_theory:
anyOf:
- type: string
- type: 'null'
title: Level Of Theory
description: Level of theory for this PartialChargesDoc.
partial_charges:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Partial Charges
description: Atomic partial charges for the molecule
type: object
title: PartialChargesComposite
description: Summary information obtained from PartialChargesDocs
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.
TypedSpeciesDict:
properties:
element:
anyOf:
- type: string
- type: 'null'
title: Element
oxidation_state:
anyOf:
- type: number
- type: 'null'
title: Oxidation State
spin:
anyOf:
- type: number
- type: 'null'
title: Spin
occu:
anyOf:
- type: number
- type: 'null'
title: Occu
type: object
title: TypedSpeciesDict
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
MetalBindingComposite:
properties:
property_id:
anyOf:
- type: string
- type: 'null'
title: Property Id
description: Property ID for this MetalBindingDoc.
level_of_theory:
anyOf:
- type: string
- type: 'null'
title: Level Of Theory
description: Level of theory for this MetalBindingDoc.
binding_partial_charges_property_id:
anyOf:
- type: string
- type: 'null'
title: Binding Partial Charges Property Id
description: ID of PartialChargesDoc used to estimate metal charge
binding_partial_spins_property_id:
anyOf:
- type: string
- type: 'null'
title: Binding Partial Spins Property Id
description: ID of PartialSpinsDoc used to estimate metal spin
binding_partial_charges_lot_solvent:
anyOf:
- type: string
- type: 'null'
title: Binding Partial Charges Lot Solvent
description: Combination of level of theory and solvent used to calculate atomic partial charges
binding_partial_spins_lot_solvent:
anyOf:
- type: string
- type: 'null'
title: Binding Partial Spins Lot Solvent
description: Combination of level of theory and solvent used to calculate atomic partial spins
binding_charge_spin_method:
anyOf:
- type: string
- type: 'null'
title: Binding Charge Spin Method
description: The method used for partial charges and spins (must be the same).
binding_bonding_property_id:
anyOf:
- type: string
- type: 'null'
title: Binding Bonding Property Id
description: ID of MoleculeBondingDoc used to detect bonding in this molecule
binding_bonding_lot_solvent:
anyOf:
- type: string
- type: 'null'
title: Binding Bonding Lot Solvent
description: Combination of level of theory and solvent used to determine the coordination environment of the metal atom or ion
binding_bonding_method:
anyOf:
- type: string
- type: 'null'
title: Binding Bonding Method
description: The method used for to define bonding.
binding_thermo_property_id:
anyOf:
- type: string
- type: 'null'
title: Binding Thermo Property Id
description: ID of MoleculeThermoDoc used to obtain this molecule's thermochemistry
binding_thermo_lot_solvent:
anyOf:
- type: string
- type: 'null'
title: Binding Thermo Lot Solvent
description: Combination of level of theory and solvent used for uncorrected thermochemistry
binding_thermo_correction_lot_solvent:
anyOf:
- type: string
- type: 'null'
title: Binding Thermo Correction Lot Solvent
description: Combination of level of theory and solvent used to correct the electronic energy
binding_thermo_combined_lot_solvent:
anyOf:
- type: string
- type: 'null'
title: Binding Thermo Combined Lot Solvent
description: Combination of level of theory and solvent used for molecular thermochemistry, combining both the frequency calculation and (potentially) the single-point energy correction.
binding_data:
anyOf:
- items:
$ref: '#/components/schemas/MetalBindingData'
type: array
- type: 'null'
title: Binding Data
description: Binding data for each metal atom or ion in the molecule
type: object
title: MetalBindingComposite
description: Summary information obtained from MetalBindingDocs
OrbitalComposite:
properties:
property_id:
anyOf:
- type: string
- type: 'null'
title: Property Id
description: Property ID for this OrbitalDoc.
level_of_theory:
anyOf:
- type: string
- type: 'null'
title: Level Of Theory
description: Level of theory for this OrbitalDoc.
open_shell:
anyOf:
- type: boolean
- type: 'null'
title: Open Shell
description: Is this molecule open-shell (spin multiplicity != 1)?
type: object
title: OrbitalComposite
description: Summary information obtained from OrbitalDocs
TypedSiteDict:
properties:
label:
anyOf:
- type: string
- type: 'null'
title: Label
name:
anyOf:
- type: string
- type: 'null'
title: Name
properties:
anyOf:
- $ref: '#/components/schemas/TypedSiteProperitesDict'
- type: 'null'
species:
anyOf:
- items:
$ref: '#/components/schemas/TypedSpeciesDict'
type: array
- type: 'null'
title: Species
abc:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Abc
xyz:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Xyz
type: object
title: TypedSiteDict
MetalBindingData:
properties:
metal_molecule_id:
type: string
pattern: ^^([A-Za-z]+-)?([A-Fa-f0-9]+)-([A-Za-z0-9]+)-(m?[0-9]+)-([0-9]+)$
title: Metal Molecule Id
description: The MPculeID of the metal atom or ion being bound
examples:
- 1a525231bdac3f13e2fac0962fe8d053-Mg1-0-1
- 22b40b99719ac570fc7e6225e855ec6e-F5Li1P1-m1-2
- mpcule-b9ba54febc77d2a9177accf4605767db-C1H41-2
nometal_molecule_id:
type: string
pattern: ^^([A-Za-z]+-)?([A-Fa-f0-9]+)-([A-Za-z0-9]+)-(m?[0-9]+)-([0-9]+)$
title: Nometal Molecule Id
description: The MPculeID of the molecule with the metal atom/ion removed
examples:
- 1a525231bdac3f13e2fac0962fe8d053-Mg1-0-1
- 22b40b99719ac570fc7e6225e855ec6e-F5Li1P1-m1-2
- mpcule-b9ba54febc77d2a9177accf4605767db-C1H41-2
metal_index:
anyOf:
- type: integer
- type: 'null'
title: Metal Index
description: Index of the metal in this Molecule (in case of a molecule with multiple identical metal atoms/ions)
metal_element:
anyOf:
- type: string
- properties:
'@class':
type: string
enum:
- Species
'@module':
type: string
enum:
- pymatgen.core.periodic_table
'@version':
type: string
type: object
required:
- '@class'
- '@module'
- $ref: '#/components/schemas/Element'
- type: 'null'
title: Metal Element
description: The metal bound to the molecule
metal_partial_charge:
anyOf:
- type: number
- type: 'null'
title: Metal Partial Charge
description: The exact calculated partial charge of the metal
metal_partial_spin:
anyOf:
- type: number
- type: 'null'
title: Metal Partial Spin
description: The exact calculated partial spin on the metal
metal_assigned_charge:
anyOf:
- type: number
- type: 'null'
title: Metal Assigned Charge
description: The integral charge assigned to this metal based on partial charge/spin data
metal_assigned_spin:
anyOf:
- type: number
- type: 'null'
title: Metal Assigned Spin
description: The integral spin multiplicity assigned to this metal based on partial spin data
number_coordinate_bonds:
anyOf:
- type: integer
- type: 'null'
title: Number Coordinate Bonds
description: The number of atoms neighboring the metal atom or ion of interest
coordinating_atoms:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Coordinating Atoms
description: The elements/species coordinating the metal.
coordinate_bond_lengths:
anyOf:
- additionalProperties:
additionalProperties:
anyOf:
- type: number
- items:
type: number
type: array
type: object
type: object
- type: 'null'
title: Coordinate Bond Lengths
description: Bond lengths and statistics broken down by the coordinating atoms
binding_energy:
anyOf:
- type: number
- type: 'null'
title: Binding Energy
description: 'The electronic energy change (∆E) of binding (units: eV)'
binding_enthalpy:
anyOf:
- type: number
- type: 'null'
title: Binding Enthalpy
description: 'The enthalpy change (∆H) of binding (units: eV)'
binding_entropy:
anyOf:
- type: number
- type: 'null'
title: Binding Entropy
description: 'The entropy change (∆S) of binding (units: eV/K)'
binding_free_energy:
anyOf:
- type: number
- type: 'null'
title: Binding Free Energy
description: 'The free energy change (∆G) of binding (units: eV)'
metal_thermo_property_id:
anyOf:
- type: string
- type: 'null'
title: Metal Thermo Property Id
description: ID of MoleculeThermoDoc used to obtain the thermochemistry of the metal atom/ion
nometal_thermo_property_id:
anyOf:
- type: string
- type: 'null'
title: Nometal Thermo Property Id
description: ID of MoleculeThermoDoc used to obtain the thermochemistry of of the molecule with the metal atom/ion removed
type: object
required:
- metal_molecule_id
- nometal_molecule_id
title: MetalBindingData
description: Metal binding information for one metal or ion in a molecule
Response_MoleculeSummaryDoc_:
properties:
data:
anyOf:
- items:
$ref: '#/components/schemas/MoleculeSummaryDoc'
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[MoleculeSummaryDoc]
ThermoComposite:
properties:
property_id:
anyOf:
- type: string
- type: 'null'
title: Property Id
description: Property ID map for this MoleculeThermoDoc
level_of_theory:
anyOf:
- type: string
- type: 'null'
title: Level Of Theory
description: Level of theory for this MoleculeThermoDoc.
electronic_energy:
anyOf:
- type: number
- type: 'null'
title: Electronic Energy
description: 'Electronic energy of the molecule (units: eV)'
zero_point_energy:
anyOf:
- type: number
- type: 'null'
title: Zero Point Energy
description: 'Zero-point energy of the molecule (units: eV)'
total_enthalpy:
anyOf:
- type: number
- type: 'null'
title: Total Enthalpy
description: 'Total enthalpy of the molecule at 298.15K (units: eV)'
total_entropy:
anyOf:
- type: number
- type: 'null'
title: Total Entropy
description: 'Total entropy of the molecule at 298.15K (units: eV/K)'
free_energy:
anyOf:
- type: number
- type: 'null'
title: Free Energy
description: 'Gibbs free energy of the molecule at 298.15K (units: eV)'
type: object
title: ThermoComposite
description: Summary information obtained from MoleculeThermoDocs
MoleculeSummaryDoc:
properties:
charge:
anyOf:
- type: integer
- type: 'null'
title: Charge
description: Charge of the molecule
spin_multiplicity:
anyOf:
- type: integer
- type: 'null'
title: Spin Multiplicity
description: Spin multiplicity of the molecule
natoms:
anyOf:
- type: integer
- type: 'null'
title: Natoms
description: Total number of atoms in the molecule
elements:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Elements
description: List of elements in the molecule
nelements:
anyOf:
- type: integer
- type: 'null'
title: Number of Elements
nelectrons:
anyOf:
- type: integer
- type: 'null'
title: Number of electrons
description: The total number of electrons for the molecule
composition:
anyOf:
- additionalProperties:
type: number
type: object
- type: 'null'
title: Composition
description: Full composition for the molecule
composition_reduced:
anyOf:
- additionalProperties:
type: number
type: object
- type: 'null'
title: Reduced Composition
description: Simplified representation of the composition
formula_alphabetical:
anyOf:
- type: string
- type: 'null'
title: Alphabetical Formula
description: Alphabetical molecular formula
formula_pretty:
anyOf:
- type: st
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/materials-project/refs/heads/main/openapi/materials-project-molecules-summary-api-openapi.yml