# Examples

## Summary Queries

### Structure data for silicon (mp-149)

```python
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:

```python
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

```python
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)

```python
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

```python
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

```python
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

```python
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)

```python
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)

```python
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)

```python
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`:

```python
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.

```psl
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)

```python
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)

```python
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:

```python
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)

```python
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

```python
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:

```python
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:

{% code overflow="wrap" %}

```python
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])
```

{% endcode %}

***

#### 2. Search by Provenance Tags and Remarks

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

{% code overflow="wrap" %}

```python
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", []))) 
]
```

{% endcode %}

***

#### 3. Combine Results

Merge both lists for a comprehensive set of perovskite materials:

{% code overflow="wrap" %}

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

{% endcode %}

***

#### 4. (Optional) Fetch Structures

<pre class="language-python" data-overflow="wrap"><code class="lang-python">with MPRester("your_api_key_here") as mpr:
    summaries = mpr.materials.summary.search(material_ids=likely_perovskite_mpids)
<strong>for summary in summaries:
</strong><strong>    print(summary.formula_pretty, summary.material_id)
</strong></code></pre>

## 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](https://github.com/materialsproject/emmet/blob/6b2b8492edfcab6e81f29b5eda1eb938d0724160/emmet-core/emmet/core/vasp/calc_types/enums.py#L87).

**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:

```python
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](https://hackingmaterials.lbl.gov/robocrystallographer/index.html) 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.

```python
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):

```python
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()
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.materialsproject.org/downloading-data/using-the-api/examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.