Examples

API query examples with the MPRester client.

Summary Queries

Structure data for silicon (mp-149)

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(material_ids=["mp-149"], fields=["structure"])
    structure = docs[0].structure
    # -- Shortcut for a single Materials Project ID:
    structure = mpr.get_structure_by_material_id("mp-149")

Querying ICSD ID

For structures tagged with at least one ICSD entry, the simplest way to query structure with ICSD ID is this:

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    mp_docs = mpr.materials.summary.search(fields=["material_id", "database_IDs"])

icsd_to_mpid = {}
for mp_doc in mp_docs:
    mpid = str(mp_doc.material_id)
    for icsd_id in mp_doc.database_IDs.get("icsd",[]):
        if icsd_id not in icsd_to_mpid:
            icsd_to_mpid[icsd_id] = []
        icsd_to_mpid[icsd_id].append(mpid)

Then the keys of icsd_to_mpid will be all ICSD IDs currently matched to at least one entry in MP, and its values will be the MP IDs which structurally match to that ICSD ID.

NOTE: Not every ICSD entry is included in Materials Project - some of them we’re working on adding, others we do not plan to add (e.g., if they are disordered with a complex disordering ratio). Furthermore, many ICSD entries can structure match to the same MP ID. We use the pymatgen StructureMatcher to determine structural similarity

Find all Materials Project IDs for entries with dielectric data

from mp_api.client import MPRester
from emmet.core.summary import HasProps

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(
        has_props = [HasProps.dielectric], fields=["material_id"]
    )
    mpids = [doc.material_id for doc in docs]

Calculation (task) IDs and types for silicon (mp-149)

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr: 
    # use core rester
    docs = mpr.materials.search(material_ids=["mp-149"], fields=["calc_types"])
    task_ids = docs[0].calc_types.keys()
    task_types = docs[0].calc_types.values() 
    # -- Shortcut for a single Materials Project ID:
    task_ids = mpr.get_task_ids_associated_with_material_id("mp-149")

Band gaps for all materials containing only Si and O

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(
        chemsys="Si-O", fields=["material_id", "band_gap"]
    )
    mpid_bgap_dict = {doc.material_id: doc.band_gap for doc in docs}

Chemical formulas for all materials containing at least Si and O

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(
        elements=["Si", "O"], fields=["material_id", "band_gap", "formula_pretty"]
    )
    mpid_formula_dict = {
        doc.material_id: doc.formula_pretty for doc in docs
    }

Material IDs for all ternary oxides with the form ABC3

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(
        chemsys="O-*-*", formula="ABC3",
        fields=["material_id"]
    )
    mpids = [doc.material_id for doc in docs]

Stable materials (on the GGA/GGA+U hull) with large band gaps (>3eV)

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(
        band_gap=(3, None), is_stable=True, fields=["material_id"]
    )
    stable_mpids = [doc.material_id for doc in docs]
    
    ## -- Alternative directly using energy above hull:
    docs = mpr.materials.summary.search(
        band_gap=(3, None), energy_above_hull=(0, 0), fields=["material_id"]
    )
    stable_mpids = [doc.material_id for doc in docs]

Electronic Structure

Band structures for silicon (mp-149)

from mp_api.client import MPRester
from emmet.core.electronic_structure import BSPathType

with MPRester("your_api_key_here") as mpr:
    # -- line-mode, Setyawan-Curtarolo (default):
    bs_sc = mpr.get_bandstructure_by_material_id("mp-149")
    
    # -- line-mode, Hinuma et al.:
    bs_hin = mpr.get_bandstructure_by_material_id("mp-149", path_type=BSPathType.hinuma)

    # -- line-mode, Latimer-Munro:
    bs_hin = mpr.get_bandstructure_by_material_id("mp-149", path_type=BSPathType.latimer_munro)
    
    # -- uniform:
    bs_uniform = mpr.get_bandstructure_by_material_id("mp-149", line_mode=False)                            

Density of states for silicon (mp-149)

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    dos = mpr.get_dos_by_material_id("mp-149")
    
# Use pymatgen's features to normalize the DOS
normalized_dos = dos.get_normalized()

# or use the associated structure in the DOS
norm_vol = dos.structure.volume

VASP Input Parameters (e.g. NELECT)

To get NELECT (or any other INCAR parameters) is by getting the task_id for the entry and then querying the tasks endpoint directly.

Suppose you want the value of NELECT for mp-149:

from pymatgen.electronic_structure.core import Spin
from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    summary_doc = mpr.materials.summary.search(material_ids=["mp-149"])[0]
    task_id = str(summary_doc.dos.total[Spin.up].task_id)
    task_doc = mpr.materials.tasks.search(task_ids=[task_id])[0]
print(task_doc.input.parameters.get("NELECT"))

NOTE: Be aware that the POTCARs we use in calculations has changed over time, the value of NELECT is not always determined by the MPRelaxSet. If a DOS was generated with r2SCAN, then the right set to use is MPScanRelaxSet. The method above circumvents this by letting you directly retrieve the value of NELECT.

Get task-id associated with DOS (mp-149)

The task-id can indicate what functional was used to generate the DOS.

from pymatgen.electronic_structure.core import Spin

with MPRester() as mpr:
    # get all electronic structure info:
    estruct_doc = mpr.materials.electronic_structure.search(material_ids=["mp-149"])[0]

    # Inspect task IDs associated with the electronic structure document
    print(f"DOS task ID = {estruct_doc.dos.total[Spin.up].task_id}")
    print(f"Band structure task ID = {estruct_doc.task_id}")

    # Retrieve the task corresponding to the electronic DOS:
    dos_task = mpr.materials.tasks.search(task_ids=[estruct_doc.dos.total[Spin.up].task_id])[0]

print(dos_task.task_id,dos_task.calc_type)

Phonons

Band structure for silicon (mp-149)

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    ph_bs = mpr.get_phonon_bandstructure_by_material_id("mp-149")

Density of states for silicon (mp-149)

from mp_api.client import MPRester
from emmet.core.electronic_structure import BSPathType

with MPRester("your_api_key_here") as mpr:
    ph_dos = mpr.get_phonon_dos_by_material_id("mp-149")

XAS

XAS for TiO2 element O K edge:

from mp_api.client import MPRester
from emmet.core.xas import Edge, XASDoc, Type

with MPRester("your_api_key_here") as mpr:
    xas = mpr.materials.xas.search(formula = "TiO2", 
                                  absorbing_element = 'Ti', 
                                  edge = Edge.K)

Charge Density

Charge density for silicon (mp-149)

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    chgcar = mpr.get_charge_density_from_material_id("mp-149")

Phase Diagram

Phase diagram for the Li-Fe-O chemical system

from mp_api.client import MPRester
from emmet.core.thermo import ThermoType

with MPRester("your_api_key_here") as mpr:
    
    # -- GGA/GGA+U/R2SCAN mixed phase diagram
    pd = mpr.materials.thermo.get_phase_diagram_from_chemsys(chemsys="Li-Fe-O", 
                                                   thermo_type=ThermoType.GGA_GGA_U_R2SCAN)
    
    # -- GGA/GGA+U mixed phase diagram
    pd = mpr.materials.thermo.get_phase_diagram_from_chemsys(chemsys="Li-Fe-O", 
                                                   thermo_type=ThermoType.GGA_GGA_U)
                                                   
    # -- R2SCAN only phase diagram
    pd = mpr.materials.thermo.get_phase_diagram_from_chemsys(chemsys="Li-Fe-O", 
                                                   thermo_type=ThermoType.R2SCAN)
   
    

Querying amorphous materials

There are some caveats with representing amorphous structures as small ordered unit cells, and the resulting structures may be phase separated or not representative of a true amorphous phase. Nevertheless, the Materials Project has "amorphous" entries for some compositions, which can be queried and filtered. The following is an example of how to obtain the Materials Project IDs for all SiO2 "amorphous" solids:

from mp_api.client import MPRester
from pymatgen.core import Composition

target_composition = Composition({"Si": 1, "O": 2})
with MPRester("your_api_key_here") as mpr:
    si_o_mpids = [
        doc.material_id
        for doc in mpr.materials.search(chemsys="Si-O", fields = ["material_id","composition_reduced"])
        if doc.composition_reduced == target_composition
    ]
    si_o_prov = mpr.materials.provenance.search(material_ids=si_o_mpids)
amorphous_si_o2_mpids = [doc.material_id.string for doc in si_o_prov if any("amorphous" in tag.lower() for tag in doc.tags)]

Searching by Crystal Prototype: Example — Perovskite

Searching for materials by formula (e.g., ABC₃) can miss important structure types like perovskites with non-standard formulas (e.g., Cs₃Sb₂I₉). Instead, you can search by crystal prototype or structure type using the Materials Project API.

1. Search by Robocrystallographer Description

Robocrystallographer generates structure descriptions, including the term "perovskite" for relevant materials:

from mp_api.client import MPRester
with MPRester("your_api_key_here") as mpr:
    robocrys_docs = mpr.materials.robocrys.search(keywords=["perovskite"])
robo_perov_mpids = [doc.material_id for doc in robocrys_docs])

---

2. Search by Provenance Tags and Remarks

Many materials have "perovskite" in their tags or remarks fields:

with MPRester("your_api_key_here",use_document_model=False) as mpr:
    prov_docs = mpr.materials.provenance.search( fields=["material_id", "remarks", "tags"] ) possible_perov = [
    doc.get("material_id") for doc in prov_docs
    if any("perovskite" in tag.lower() for tag in (doc.get("tags", []) + doc.get("remarks", []))) 
]

---

3. Combine Results

Merge both lists for a comprehensive set of perovskite materials:

likely_perovskite_mpids = list(set(robo_perov_mpids).union(possible_perov))

---

4. (Optional) Fetch Structures

with MPRester("your_api_key_here") as mpr:
    summaries = mpr.materials.summary.search(material_ids=likely_perovskite_mpids)
for summary in summaries:
    print(summary.formula_pretty, summary.material_id)

Querying specialized calculations like DFPT

MP contains specialized calculations to compute various materials properties. Sometimes it's of interest to find those calculations. A full list of valid such "task types" are given in our builder software, emmet.

DFPT outputs and data only exist for parts of our database. The following code snippet will take only relevant task (single DFT calculation) data from our database and check to see if it’s a DFPT calculation:

from mp_api.client import MPRester

with MPRester("your_api_key_here",use_document_model=False,monty_decode=False) as mpr:
    tasks = mpr.materials.tasks.search(fields=["task_id","task_type"])
    
dfpt_tasks = {
    task["task_id"] for task in tasks if task["task_type"] in {"DFPT", "DFPT Dielectric"}
}

dfpt_tasks will contain a set of task IDs which you can then query like mpr.materials.tasks.search(task_ids=dfpt_tasks)

Identifying Materials with Specific Structural Dimensionalities

Though the Materials Project does not store structure dimension as a formal property, it is possible to categorize entries by their structure dimension (1D, 2D, and 3D) by parsing robocrystallographer analyses, which are generated for most materials in the Materials Project.

Finding Materials by Dimension in a Chemical System

Here's an example for the Mo-S system. Note how separate queries are used to retrieve material documents and robocrystallographer entries. These two entities must be associated with each other manually.

from mp_api.client import MPRester

chemsys = "Mo-S"
with MPRester("your_api_key") as mpr:
    mat_docs = mpr.materials.search(chemsys=chemsys, fields=["material_id","structure"])
    robo_docs = mpr.materials.robocrys.search_docs(material_ids=[doc.material_id for doc in mat_docs])

mpid_to_structure = {doc.material_id.string: doc.structure for doc in mat_docs}
structures_by_dim = {"1D": {}, "2D": {}, "3D": {}}
int_to_word = {1: "one", 2: "two"}

for doc in robo_docs:
    for i in range(1, 3):
        if f"{int_to_word[i]}-dimensional" in doc.description.lower():
            dim = i
            break
        else:
            dim = 3
    structures_by_dim[f"{dim}D"][doc.material_id.string] = {
        "structure": mpid_to_structure[doc.material_id.string],
        "description": doc.description,
    }

Searching for All Dimensional Forms

To find chemical systems with materials existing in all three forms (1D, 2D, and 3D):

from mp_api.client import MPRester
from collections import defaultdict

with MPRester("your_api_key") as mpr:
    mat_docs = mpr.materials.search(fields=['composition', 'material_id'])
    robo_docs = mpr.materials.robocrys.search_docs()

description_by_mpid = {doc.material_id: doc.description for doc in robo_docs}
formula_to_mpids = defaultdict(list)

for doc in mat_docs:
    formula = doc.composition.reduced_formula
    mpid = doc.material_id
    formula_to_mpids[formula].append(mpid)

mpid_to_dim = {}
int_to_word = {1: "one", 2: "two"}

for mpid, desc in description_by_mpid.items():
    for i in range(1, 3):
        if f"{int_to_word[i]}-dimensional" in desc.lower():
            mpid_to_dim[mpid] = f"{i}D"
            break
        else:
            mpid_to_dim[mpid] = "Other"

results = {}
for formula, mpids in formula_to_mpids.items():
    dim_to_mpids = {"1D": [], "2D": [], "Other": []}
    for mpid in mpids:
        if mpid in mpid_to_dim:
            dim = mpid_to_dim[mpid]
            dim_to_mpids[dim].append(mpid)
    if all(dim_to_mpids[d] for d in ["1D", "2D", "Other"]):
        results[formula] = dim_to_mpids

for i, (formula, dims) in enumerate(results.items(), 1):
    print(f"{i}- Chemical system: {formula}")
    for dim in ["1D", "2D", "Other"]:
        mpids = dims[dim]
        print(f"   - {len(mpids)} {dim} structures:")
        for mpid in mpids:
            print(f"       - {mpid}")
    print()