Skip to content

The Materials API

In this lesson, we cover:

  • The (new) Materials Project API (MAPI) and its documentation (https://api.materialsproject.org/).
  • Getting your Materials Project API key.
  • Using the MPRester to access the MP database.
  • A hands-on example of using the API and pymatgen to screen the MP database for interesting materials.
# This supresses warnings.
import warnings
warnings.filterwarnings('ignore')

# This is a helper function to shorten lists during the 
# live presentation of this lesson for better readability. 
# You can ignore it. 
def shortlist(long_list, n=5):
    print("First {} of {} items:".format(min(n, 5), len(long_list)))
    for item in long_list[0:n]:
        print(item)

Section 0: Installing the Materials Project API client

The new API client can be installed using pip: pip install mp-api

NOTE: If you are doing this lesson in CoCalc, the package should already be installed.


Section 1: Getting an API key

The first step to getting started with the API is to get an API key. This can be done on the next-gen preview Materials Project website (https://next-gen.materialsproject.org.)

  1. Log in using your account of choice.
  2. Click API in the top right of the homepage.
  3. Copy and paste your API key in the command below, or set the appropriate environment variable.
#MP_API_KEY="<your API key>"

import os
MP_API_KEY=os.environ.get("MP_API_KEY")

Section 2: Documentation

A description of the new Materials Project API can be found on the API details page. This, along with the more detailed documentation it links to, are a key source of information regarding what data can be queried for. It should be the first thing you consult whenever you are having trouble with the API.

The API is organized into into different endpoints that provided access to different types of data:


Section 3: API Requests

Data from the API can be accessed through REST requests.

REST is a widely used type of standardization that allows different computer systems to work together. In RESTful systems, information is organized into resources, each of which is uniquely identified via a uniform resource identifier (URI). Since the Materials Project API is a RESTful system, users can interact with the MP database regardless of their computer system or programming language (as long as it supports basic http requests.)

To request data from the Materials Project, you will need to make requests to our API. To do this, you could simply make a GET HTTP request providing your API key as an argument in the header of the request.

Below is an example of this using the requests package in python.

import os
import requests

response = requests.get("https://api.materialsproject.org/materials/mp-149/?fields=material_id%2Cstructure&all_fields=false", 
                        headers={"X-API-KEY": MP_API_KEY})

print(response.text)
{"data":[{"_id":"60b7d8ddb671aa7b01a7ce04","material_id":"mp-149","structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":null,"lattice":{"matrix":[[5.468728,0.0,3.348630120303753e-16],[8.794385361720812e-16,5.468728,3.348630120303753e-16],[0.0,0.0,5.468728]],"a":5.468728,"b":5.468728,"c":5.468728,"alpha":90.0,"beta":90.0,"gamma":90.0,"volume":163.55317139465933},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.75,0.25],"xyz":[1.3671820000000006,4.101546,1.3671820000000003],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.0,0.5],"xyz":[0.0,0.0,2.734364],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.75],"xyz":[1.3671820000000001,1.367182,4.101546],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.5,0.0],"xyz":[4.397192680860406e-16,2.734364,1.6743150601518765e-16],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.75,0.75,0.75],"xyz":[4.101546000000001,4.101546,4.101546000000001],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.5,0.0,0.0],"xyz":[2.734364,0.0,1.6743150601518765e-16],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.75,0.25,0.25],"xyz":[4.101546,1.367182,1.3671820000000003],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.5,0.5,0.5],"xyz":[2.7343640000000002,2.734364,2.7343640000000002],"label":"Si","properties":{}}]}}]}

The above request for the material id and structure of Si (mp-149) should return the following JSON document:

{"data":[{"_id":"60b7d8ddb671aa7b01a7ce04","material_id":"mp-149","structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":null,"lattice":{"matrix":[[5.468728,0.0,3.348630120303753e-16],[8.794385361720812e-16,5.468728,3.348630120303753e-16],[0.0,0.0,5.468728]],"a":5.468728,"b":5.468728,"c":5.468728,"alpha":90.0,"beta":90.0,"gamma":90.0,"volume":163.55317139465933},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.75,0.25],"xyz":[1.3671820000000006,4.101546,1.3671820000000003],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.0,0.5],"xyz":[0.0,0.0,2.734364],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.75],"xyz":[1.3671820000000001,1.367182,4.101546],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.5,0.0],"xyz":[4.397192680860406e-16,2.734364,1.6743150601518765e-16],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.75,0.75,0.75],"xyz":[4.101546000000001,4.101546,4.101546000000001],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.5,0.0,0.0],"xyz":[2.734364,0.0,1.6743150601518765e-16],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.75,0.25,0.25],"xyz":[4.101546,1.367182,1.3671820000000003],"label":"Si","properties":{}},{"species":[{"element":"Si","occu":1}],"abc":[0.5,0.5,0.5],"xyz":[2.7343640000000002,2.734364,2.7343640000000002],"label":"Si","properties":{}}]}}]}


Section 4: The MPRester

To facilitate researchers in using our API, we implemented a convenient wrapper for it called the MPRester.

This python class contains many convenience methods for easily accessing data from the API without having to issue direct REST requests.

Starting up an instance of the MPRester

We'll import the MPRester and create an instance of it.

Note: You may need to use your API key as an input argument if it has not been pre-configured.

from mp_api.matproj import MPRester

mpr = MPRester(MP_API_KEY)
mpr.materials.available_fields
['emmet_version',
 'pymatgen_version',
 'build_date',
 'structure',
 'nsites',
 'elements',
 'nelements',
 'composition',
 'composition_reduced',
 'formula_pretty',
 'formula_anonymous',
 'chemsys',
 'volume',
 'density',
 'density_atomic',
 'symmetry',
 'material_id',
 'deprecated',
 'initial_structures',
 'task_ids',
 'deprecated_tasks',
 'calc_types',
 'last_updated',
 'created_at',
 'origins',
 'warnings']

However, we recommend that you use the “with” context manager to ensure that sessions are properly closed after usage:

with MPRester(MP_API_KEY) as mpr:
    print(mpr.thermo.available_fields)
['emmet_version', 'pymatgen_version', 'build_date', 'structure', 'nsites', 'elements', 'nelements', 'composition', 'composition_reduced', 'formula_pretty', 'formula_anonymous', 'chemsys', 'volume', 'density', 'density_atomic', 'symmetry', 'property_name', 'material_id', 'last_updated', 'origins', 'warnings', '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', 'energy_type', 'entry_types', 'entries']

MPRester Methods:

The MPRester has many methods that you might want to use in your research. For example, there is a method to get the bandstructure for a material, get_bandstructure_by_material_id.

Let's use this method and the following bandstructure plotting function to get and plot a bandstructure for mp-1234:

### Don't edit this code ####
from pymatgen.electronic_structure.plotter import BSPlotter
# Helpful function for plotting a bandstructure. 
def plot_bandstructure(bs):
    BSPlotter(bs).get_plot().show() 
#############################
# Use the MPRester's get_bandstructure_by_material_id method to 
# get a bandstructure from the MP Database and plot it using the
# plot_bandstructure functin defined above.
with MPRester(MP_API_KEY) as mpr:
    bs = mpr.get_bandstructure_by_material_id("mp-1234")

plot_bandstructure(bs) 

There's also a method to get MPIDs for a formula or chemical system called get_materials_ids.

with MPRester(MP_API_KEY) as mpr:
    # You can pass in a formula to get_materials_ids
    shortlist(mpr.get_materials_ids("LiFePO4"))
    # Or you can pass in a "chemsys" such as "Li-Fe-P-O"
    shortlist(mpr.get_materials_ids("Li-Fe-P-O"))
First 5 of 70 items:
mp-18951
mp-19017
mp-26041
mp-26559
mp-26611
First 5 of 388 items:
mp-6373
mp-18951
mp-19017
mp-19294
mp-19430

Using the API to achieve research goals:

Imagine you want to get the structure for the ferroelectric material \(Ca_3Ti_2O_7\) (mp-4163) and suggest some substrates for growing it.

We can use methods of the MPRester to get this information from the Materials Project API.

Hints:

  • MPRester.get_structure_by_material_id
  • MPRester.get_substrates
# Get the structure for Ca3Ti2O7 (mp-4163) and 
# suggest some substrates for growing it.
with MPRester(MP_API_KEY) as mpr:
    structure = mpr.get_structure_by_material_id("mp-4163")
    substrates = mpr.get_substrates("mp-4163")
    print(structure)
    print([s["sub_form"] for s in substrates])
Full Formula (Ca12 Ti8 O28)
Reduced Formula: Ca3Ti2O7
abc   :   5.463042  19.475586   5.537287
angles:  90.000000  90.000000  90.000000
Sites (48)
  #  SP           a         b         c
---  ----  --------  --------  --------
  0  Ca    0.253586  0         0.038816
  1  Ca    0.746414  0         0.538816
  2  Ca    0.241473  0.687655  0.455977
  3  Ca    0.258527  0.812345  0.955977
  4  Ca    0.741473  0.812345  0.455977
  5  Ca    0.758527  0.687655  0.955977
  6  Ca    0.753586  0.5       0.038816
  7  Ca    0.246414  0.5       0.538816
  8  Ca    0.741473  0.187655  0.455977
  9  Ca    0.758527  0.312345  0.955977
 10  Ca    0.241473  0.312345  0.455977
 11  Ca    0.258527  0.187655  0.955977
 12  Ti    0.751218  0.600015  0.488523
 13  Ti    0.748782  0.899985  0.988523
 14  Ti    0.248782  0.600015  0.988523
 15  Ti    0.251218  0.899985  0.488523
 16  Ti    0.251218  0.100015  0.488523
 17  Ti    0.248782  0.399985  0.988523
 18  Ti    0.748782  0.100015  0.988523
 19  Ti    0.751218  0.399985  0.488523
 20  O     0.04164   0.886597  0.215103
 21  O     0.45836   0.613403  0.715103
 22  O     0.95836   0.886597  0.715103
 23  O     0.54164   0.613403  0.215103
 24  O     0.538871  0.916205  0.297016
 25  O     0.961129  0.583795  0.797016
 26  O     0.461129  0.916205  0.797016
 27  O     0.038871  0.583795  0.297016
 28  O     0.681782  0.802249  0.026129
 29  O     0.818218  0.697751  0.526129
 30  O     0.82435   0         0.987288
 31  O     0.17565   0         0.487288
 32  O     0.181782  0.697751  0.026129
 33  O     0.318218  0.802249  0.526129
 34  O     0.54164   0.386597  0.215103
 35  O     0.95836   0.113403  0.715103
 36  O     0.45836   0.386597  0.715103
 37  O     0.04164   0.113403  0.215103
 38  O     0.038871  0.416205  0.297016
 39  O     0.461129  0.083795  0.797016
 40  O     0.961129  0.416205  0.797016
 41  O     0.538871  0.083795  0.297016
 42  O     0.181782  0.302249  0.026129
 43  O     0.318218  0.197751  0.526129
 44  O     0.32435   0.5       0.987288
 45  O     0.67565   0.5       0.487288
 46  O     0.681782  0.197751  0.026129
 47  O     0.818218  0.302249  0.526129
['Si', 'CeO2', 'TbScO3', 'GaN', 'LiGaO2', 'C', 'NdGaO3', 'LiGaO2', 'GaP', 'DyScO3', 'Mg', 'LiGaO2', 'SiO2', 'Bi2Te3', 'LiF', 'CaF2', 'GaN', 'GaP', 'BN', 'GdScO3', 'DyScO3', 'Si', 'CeO2', 'LaAlO3', 'Si', 'CeO2', 'C', 'ZnO', 'C', 'InAs', 'NdGaO3', 'ZnTe', 'NdGaO3', 'CaF2', 'Mg', 'TiO2', 'YAlO3', 'LiAlO2', 'Ga2O3', 'CdWO4', 'NdGaO3', 'LaAlO3', 'SiC', 'TbScO3', 'TiO2', 'AlN', 'AlN', 'TiO2', 'WS2', 'MoS2', 'SiO2', 'MgAl2O4', 'Ni', 'LiAlO2', 'TiO2', 'SrTiO3', 'Ga2O3', 'ZnO', 'SiC', 'SiC', 'GaN', 'SiC', 'LaAlO3', 'GaSe', 'SiC', 'CdSe', 'YVO4', 'CsI', 'DyScO3', 'TeO2', 'Te2Mo', 'Ge', 'DyScO3', 'LiGaO2', 'GaSb', 'GaN', 'TbScO3', 'TiO2', 'TbScO3', 'GaP', 'CdWO4', 'GaSe', 'YAlO3', 'GdScO3', 'SrTiO3', 'Cu', 'Ni', 'PbSe', 'ZrO2', 'GaAs', 'TeO2', 'YAlO3', 'NaCl', 'Al', 'BaTiO3', 'CaF2', 'TeO2', 'GaTe', 'GdScO3', 'ZrO2', 'GdScO3', 'MgF2', 'GdScO3', 'BN', 'ZnSe', 'MoS2', 'SiC', 'SrTiO3', 'TeO2', 'SiC', 'NaCl', 'Ag', 'C', 'YAlO3', 'BN', 'NdGaO3', 'SiC', 'ZrO2', 'CdWO4', 'KTaO3', 'KTaO3', 'C', 'AlN', 'ZnO', 'KTaO3', 'Cu', 'TiO2', 'TiO2', 'Mg', 'Te2Mo', 'AlN', 'C', 'TbScO3', 'Fe3O4', 'Au', 'WS2', 'BaTiO3', 'Mg', 'SiC', 'NdGaO3', 'ZnO', 'SrTiO3', 'YVO4', 'ZrO2', 'DyScO3', 'ZnO', 'Al2O3', 'MgO', 'TiO2', 'MgF2', 'TiO2', 'InP', 'Y3Fe5O12', 'BaF2', 'PbS', 'BaTiO3', 'MgF2', 'DyScO3', 'BaTiO3', 'TbScO3']

At this point, you should be comfortable with:

  • Finding documentation on the MPRester.
  • Creating an instance of the MPRester.
  • Using methods of the MPRester.

Section 5: Using the MPRester.query method.

The MPRester has a very powerful method called query, which allows us to search over aggregate data for a material in our database. You will probably find yourself using the MPRester's query method frequently...

The method returns a list of SummaryDoc objects which contain the data for the material as attributes.

Let's try out some queries to learn how it works!

First, we'll query for \(SiO_2\) compounds in a variety of ways using through chemsys_formula.

# Here we query with the explicit formula
with MPRester(MP_API_KEY) as mpr:
    results = mpr.query(chemsys_formula="SiO2")
    print(len(results))
320

# Here we query with the chemical system (chemsys)
with MPRester(MP_API_KEY) as mpr:
    results = mpr.query(chemsys_formula="Si-O")
    print(len(results))
342

If we investigate the object that the query method returns, we find that it is a list of SummaryDoc objects.

print('Results are returned as a {} of {}.\n'.format(type(results), type(results[0])))

print(results[0])
Results are returned as a <class 'list'> of <class 'emmet.core.summary.SummaryDoc'>.

emmet_version='0.9.3' pymatgen_version='2022.0.11' build_date=datetime.datetime(2021, 8, 10, 2, 26, 27, 197827) structure=Structure Summary
Lattice
    abc : 9.211003801524265 9.211003801524265 5.254573
 angles : 90.0 90.0 120.00000000000001
 volume : 386.0841605832532
      A : 4.605501900762133 -7.976963286475051 0.0
      B : 4.605501900762133 7.976963286475051 0.0
      C : 0.0 0.0 5.254573
PeriodicSite: Si (4.6055, 0.9329, 3.9409) [0.4415, 0.5585, 0.7500]
PeriodicSite: Si (6.1003, -3.5220, 1.3136) [0.8830, 0.4415, 0.2500]
PeriodicSite: Si (3.1107, -3.5220, 1.3136) [0.5585, 0.1170, 0.2500]
PeriodicSite: Si (4.6055, -0.9329, 1.3136) [0.5585, 0.4415, 0.2500]
PeriodicSite: Si (6.1003, 3.5220, 3.9409) [0.4415, 0.8830, 0.7500]
PeriodicSite: Si (3.1107, 3.5220, 3.9409) [0.1170, 0.5585, 0.7500]
PeriodicSite: O (3.2796, 1.8935, 3.9409) [0.2374, 0.4747, 0.7500]
PeriodicSite: O (5.9314, -1.8935, 1.3136) [0.7626, 0.5253, 0.2500]
PeriodicSite: O (2.3028, 3.9885, 2.6273) [0.0000, 0.5000, 0.5000]
PeriodicSite: O (4.6055, 0.0000, 0.0000) [0.5000, 0.5000, 0.0000]
PeriodicSite: O (4.6055, -4.1900, 1.3136) [0.7626, 0.2374, 0.2500]
PeriodicSite: O (4.6055, 4.1900, 3.9409) [0.2374, 0.7626, 0.7500]
PeriodicSite: O (5.9314, 1.8935, 3.9409) [0.5253, 0.7626, 0.7500]
PeriodicSite: O (2.3028, 3.9885, 0.0000) [0.0000, 0.5000, 0.0000]
PeriodicSite: O (2.3028, -3.9885, 0.0000) [0.5000, 0.0000, 0.0000]
PeriodicSite: O (3.2796, -1.8935, 1.3136) [0.4747, 0.2374, 0.2500]
PeriodicSite: O (4.6055, 0.0000, 2.6273) [0.5000, 0.5000, 0.5000]
PeriodicSite: O (2.3028, -3.9885, 2.6273) [0.5000, 0.0000, 0.5000] nsites=18 elements=[Element O, Element Si] nelements=2 composition=Comp: Si6 O12 composition_reduced=Comp: Si1 O2 formula_pretty='SiO2' formula_anonymous='AB2' chemsys='O-Si' volume=386.0841605832532 density=1.5505271278975454 density_atomic=21.449120032402956 symmetry=SymmetryData(crystal_system=<CrystalSystem.hex_: 'Hexagonal'>, symbol='P6_3/mmc', number=194, point_group='6/mmm', symprec=0.1, version='1.16.1') property_name='summary' material_id=MPID(mp-559928) last_updated=datetime.datetime(2021, 7, 15, 23, 53, 28, 442000) origins=[] warnings=[] deprecated=False uncorrected_energy_per_atom=-7.890166187222222 energy_per_atom=-7.890166187222222 formation_energy_per_atom=-3.241087510555556 energy_above_hull=0.026091682777776626 is_stable=False equillibrium_reaction_energy_per_atom=None decomposes_to=[DecompositionProduct(material_id=MPID(mp-546794), formula='Si2 O4', amount=1.0)] xas=[XASSearchData(edge=<Edge.K: 'K'>, absorbing_element=Element O, spectrum_type=<Type.XANES: 'XANES'>), XASSearchData(edge=<Edge.K: 'K'>, absorbing_element=Element Si, spectrum_type=<Type.XANES: 'XANES'>), XASSearchData(edge=<Edge.K: 'K'>, absorbing_element=Element Si, spectrum_type=<Type.XAFS: 'XAFS'>), XASSearchData(edge=<Edge.K: 'K'>, absorbing_element=Element O, spectrum_type=<Type.XAFS: 'XAFS'>), XASSearchData(edge=<Edge.K: 'K'>, absorbing_element=Element Si, spectrum_type=<Type.EXAFS: 'EXAFS'>), XASSearchData(edge=<Edge.K: 'K'>, absorbing_element=Element O, spectrum_type=<Type.EXAFS: 'EXAFS'>)] grain_boundaries=None band_gap=5.4895 cbm=3.0558 vbm=-2.4337 efermi=-2.37978889 is_gap_direct=True is_metal=False es_source_calc_id=MPID(mp-699732) bandstructure=BandstructureData(setyawan_curtarolo=BandStructureSummaryData(task_id=MPID(mp-699732), band_gap=5.4895, cbm={'band_index': {'1': [48]}, 'kpoint_index': [0, 25, 26], 'kpoint': <pymatgen.electronic_structure.bandstructure.Kpoint object at 0x7f35269cd580>, 'energy': 3.0558, 'projections': {'1': [[0.0138, 0.0138, 0.0138, 0.0138, 0.0138, 0.0138, 0.0121, 0.0121, 0.0137, 0.0137, 0.0121, 0.0121, 0.0121, 0.0137, 0.0137, 0.0121, 0.0137, 0.0137], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0015, 0.0015, 0.0, 0.0, 0.0004, 0.0004, 0.0004, 0.0, 0.0, 0.0004, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0011, 0.0011, 0.0011, 0.0, 0.0, 0.0011, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]]}}, vbm={'band_index': {'1': [46, 47]}, 'kpoint_index': [0, 25, 26], 'kpoint': <pymatgen.electronic_structure.bandstructure.Kpoint object at 0x7f35269cd100>, 'energy': -2.4337, 'projections': {'1': [[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0206, 0.041, 0.0, 0.0, 0.0, 0.0206, 0.0287, 0.0, 0.041, 0.0287], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0653, 0.0653, 0.0146, 0.0076, 0.035, 0.035, 0.0673, 0.0146, 0.0142, 0.0673, 0.0076, 0.0142], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0373, 0.0232, 0.0, 0.0, 0.0, 0.0373, 0.0296, 0.0, 0.0232, 0.0296], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]]}}, efermi=-2.37978889, is_gap_direct=True, is_metal=False, magnetic_ordering='NM', nbands=94.0, equivalent_labels={'setyawan_curtarolo': {'latimer_munro': {'\\Gamma': 'Γ', 'A': 'c', 'H': 'q', 'K': 'd', 'L': 'e', 'M': 'a'}, 'hinuma': {'\\Gamma': 'GAMMA', 'A': 'A', 'H': 'H', 'K': 'K', 'L': 'L', 'M': 'M'}}, 'latimer_munro': {'setyawan_curtarolo': {'Γ': '\\Gamma', 'q': 'H', 'e': 'L', 'c': 'A', 'd': 'K', 'a': 'M'}, 'hinuma': {'Γ': 'GAMMA', 'q': 'H', 'e': 'L', 'c': 'A', 'd': 'K', 'a': 'M'}}, 'hinuma': {'setyawan_curtarolo': {'GAMMA': '\\Gamma', 'A': 'A', 'K': 'K', 'H': 'H', 'M': 'M', 'L': 'L', 'H_2': 'H^{*}'}, 'latimer_munro': {'GAMMA': 'Γ', 'A': 'c', 'K': 'd', 'H': 'q', 'M': 'a', 'L': 'e', 'H_2': 'q^{*}'}}}, direct_gap=5.4895), hinuma=None, latimer_munro=None) dos=DosData(total={'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.6518999999999995, cbm=3.2801, vbm=-2.3718, efermi=-2.41690633, spin_polarization=None)}, elemental={Element Si: {'total': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.712, cbm=3.2801, vbm=-2.4319, efermi=-2.41690633, spin_polarization=None)}, 's': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.8924, cbm=3.2801, vbm=-2.6123, efermi=-2.41690633, spin_polarization=None)}, 'p': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.712, cbm=3.2801, vbm=-2.4319, efermi=-2.41690633, spin_polarization=None)}, 'd': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=36.0759, cbm=12.5997, vbm=-23.4762, efermi=-2.41690633, spin_polarization=None)}}, Element O: {'total': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.6518999999999995, cbm=3.2801, vbm=-2.3718, efermi=-2.41690633, spin_polarization=None)}, 's': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.8323, cbm=3.2801, vbm=-2.5522, efermi=-2.41690633, spin_polarization=None)}, 'p': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.6518999999999995, cbm=3.2801, vbm=-2.3718, efermi=-2.41690633, spin_polarization=None)}, 'd': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=36.0759, cbm=12.5997, vbm=-23.4762, efermi=-2.41690633, spin_polarization=None)}}}, orbital={'s': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.8323, cbm=3.2801, vbm=-2.5522, efermi=-2.41690633, spin_polarization=None)}, 'p': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=5.6518999999999995, cbm=3.2801, vbm=-2.3718, efermi=-2.41690633, spin_polarization=None)}, 'd': {'1': DosSummaryData(task_id=MPID(mp-678482), band_gap=36.0759, cbm=12.5997, vbm=-23.4762, efermi=-2.41690633, spin_polarization=None)}}, magnetic_ordering='NM') dos_energy_up=None dos_energy_down=None ordering='NM' total_magnetization=0.0 total_magnetization_normalized_vol=0.0 total_magnetization_normalized_formula_units=0.0 num_magnetic_sites=0 num_unique_magnetic_sites=0 types_of_magnetic_species=[] k_voigt=None k_reuss=None k_vrh=None g_voigt=None g_reuss=None g_vrh=None universal_anisotropy=None homogeneous_poisson=None e_total=2.989333333332553 e_ionic=1.1583333333325483 e_electronic=1.8310000000000046 n=1.3531444860028823 e_ij_max=None weighted_surface_energy_EV_PER_ANG2=None weighted_surface_energy=None weighted_work_function=None surface_anisotropy=None shape_factor=None has_reconstructed=None has_props=['materials', 'magnetism', 'bandstructure', 'thermo', 'dos', 'dielectric', 'electronic_structure', 'xas'] theoretical=False

To access data within the document model, we can either call different attributes, or convert to a python dict and access with keys. Let's try accessing the material_id and structure using both approaches for the first entry in the list.

# Access data as an attribute
doc = results[0]

material_id = doc.material_id
print(material_id, "\n")

structure = doc.structure
print(structure)
mp-559928 

Full Formula (Si6 O12)
Reduced Formula: SiO2
abc   :   9.211004   9.211004   5.254573
angles:  90.000000  90.000000 120.000000
Sites (18)
  #  SP           a         b     c
---  ----  --------  --------  ----
  0  Si    0.441525  0.558475  0.75
  1  Si    0.88305   0.441525  0.25
  2  Si    0.558475  0.11695   0.25
  3  Si    0.558475  0.441525  0.25
  4  Si    0.441525  0.88305   0.75
  5  Si    0.11695   0.558475  0.75
  6  O     0.237371  0.474742  0.75
  7  O     0.762629  0.525258  0.25
  8  O     0         0.5       0.5
  9  O     0.5       0.5       0
 10  O     0.762629  0.237371  0.25
 11  O     0.237371  0.762629  0.75
 12  O     0.525258  0.762629  0.75
 13  O     0         0.5       0
 14  O     0.5       0         0
 15  O     0.474742  0.237371  0.25
 16  O     0.5       0.5       0.5
 17  O     0.5       0         0.5

# Access data through dictionary keys
doc = results[0].dict()

material_id = doc["material_id"]
print(material_id, "\n")

structure = doc["structure"]
print(structure)
mp-559928 

Full Formula (Si6 O12)
Reduced Formula: SiO2
abc   :   9.211004   9.211004   5.254573
angles:  90.000000  90.000000 120.000000
Sites (18)
  #  SP           a         b     c
---  ----  --------  --------  ----
  0  Si    0.441525  0.558475  0.75
  1  Si    0.88305   0.441525  0.25
  2  Si    0.558475  0.11695   0.25
  3  Si    0.558475  0.441525  0.25
  4  Si    0.441525  0.88305   0.75
  5  Si    0.11695   0.558475  0.75
  6  O     0.237371  0.474742  0.75
  7  O     0.762629  0.525258  0.25
  8  O     0         0.5       0.5
  9  O     0.5       0.5       0
 10  O     0.762629  0.237371  0.25
 11  O     0.237371  0.762629  0.75
 12  O     0.525258  0.762629  0.75
 13  O     0         0.5       0
 14  O     0.5       0         0
 15  O     0.474742  0.237371  0.25
 16  O     0.5       0.5       0.5
 17  O     0.5       0         0.5

You can even use wildcard characters in chemsys_formula searches. For example, if we want to find all \(ABO_3\) compounds in the Materials Project:

with MPRester(MP_API_KEY) as mpr:
    results = mpr.query(chemsys_formula='**O3', fields=["material_id", "formula_pretty"])
    data_list = [(result.material_id, result.formula_pretty) for result in results]
Retrieving SummaryDoc documents:  79%|███████▊  | 2000/2541 [00:00<00:00, 7322.15it/s]
shortlist(data_list)
First 5 of 2541 items:
(MPID(mp-1203293), 'NaNbO3')
(MPID(mp-1185996), 'MnBO3')
(MPID(mp-504651), 'CsVO3')
(MPID(mp-675625), 'KNO3')
(MPID(mp-1075973), 'SmMnO3')


Section 6: Accessing more detailed properties

The query method lets us search through some aggregate data but not all.

To query all available data of a particular category, specific search methods can be used.

For example, let's query for initial structures for all cubic materials with 2 or less atomic sites using the materials specific search method:

with MPRester(MP_API_KEY) as mpr:
    results = mpr.materials.search_material_docs(crystal_system="Cubic", 
                                                nsites=(0,2), 
                                                all_fields=False, 
                                                fields=["material_id", "initial_structures"])
print('Results are returned as a {} of {}.\n'.format(type(results), type(results[0])))

print(results[0])
Results are returned as a <class 'list'> of <class 'emmet.core.material.MaterialsDoc'>.

emmet_version='0.9.3' pymatgen_version='2022.0.11' build_date=datetime.datetime(2021, 8, 10, 2, 26, 28, 356414) structure=None nsites=None elements=None nelements=None composition=None composition_reduced=None formula_pretty=None formula_anonymous=None chemsys=None volume=None density=None density_atomic=None symmetry=None material_id=MPID(mp-1239193) deprecated=True initial_structures=[Structure Summary
Lattice
    abc : 6.037829 3.018914 3.018914
 angles : 90.0 90.0 90.0
 volume : 55.027817955535625
      A : 6.037829 0.0 0.0
      B : 0.0 3.018914 0.0
      C : 0.0 0.0 3.018914
PeriodicSite: Rh (1.5095, 1.5095, 1.5095) [0.2500, 0.5000, 0.5000]
PeriodicSite: Rh (4.5284, 1.5095, 1.5095) [0.7500, 0.5000, 0.5000], Structure Summary
Lattice
    abc : 5.086717 2.548028 2.548028
 angles : 90.0 90.0 90.0
 volume : 33.02523894343128
      A : 5.086717 0.0 0.0
      B : 0.0 2.548028 0.0
      C : 0.0 0.0 2.548028
PeriodicSite: Rh (1.2717, 1.2740, 1.2740) [0.2500, 0.5000, 0.5000]
PeriodicSite: Rh (3.8150, 1.2740, 1.2740) [0.7500, 0.5000, 0.5000]] task_ids=[] deprecated_tasks=[] calc_types=None last_updated=datetime.datetime(2021, 8, 10, 2, 26, 28, 356488) created_at=datetime.datetime(2021, 8, 10, 2, 26, 28, 356489) origins=None warnings=[]

Much like the SummaryDoc we can access data of MaterialsDoc through it's attributes, or by conversion to a python dictionary.

results[0].material_id, results[0].initial_structures
(MPID(mp-1239193),
 [Structure Summary
  Lattice
      abc : 6.037829 3.018914 3.018914
   angles : 90.0 90.0 90.0
   volume : 55.027817955535625
        A : 6.037829 0.0 0.0
        B : 0.0 3.018914 0.0
        C : 0.0 0.0 3.018914
  PeriodicSite: Rh (1.5095, 1.5095, 1.5095) [0.2500, 0.5000, 0.5000]
  PeriodicSite: Rh (4.5284, 1.5095, 1.5095) [0.7500, 0.5000, 0.5000],
  Structure Summary
  Lattice
      abc : 5.086717 2.548028 2.548028
   angles : 90.0 90.0 90.0
   volume : 33.02523894343128
        A : 5.086717 0.0 0.0
        B : 0.0 2.548028 0.0
        C : 0.0 0.0 2.548028
  PeriodicSite: Rh (1.2717, 1.2740, 1.2740) [0.2500, 0.5000, 0.5000]
  PeriodicSite: Rh (3.8150, 1.2740, 1.2740) [0.7500, 0.5000, 0.5000]])
results[0].dict()
{'emmet_version': '0.9.3',
 'pymatgen_version': '2022.0.11',
 'build_date': datetime.datetime(2021, 8, 10, 2, 26, 28, 356414),
 'structure': None,
 'nsites': None,
 'elements': None,
 'nelements': None,
 'composition': None,
 'composition_reduced': None,
 'formula_pretty': None,
 'formula_anonymous': None,
 'chemsys': None,
 'volume': None,
 'density': None,
 'density_atomic': None,
 'symmetry': None,
 'material_id': MPID(mp-1239193),
 'deprecated': True,
 'initial_structures': [Structure Summary
  Lattice
      abc : 6.037829 3.018914 3.018914
   angles : 90.0 90.0 90.0
   volume : 55.027817955535625
        A : 6.037829 0.0 0.0
        B : 0.0 3.018914 0.0
        C : 0.0 0.0 3.018914
  PeriodicSite: Rh (1.5095, 1.5095, 1.5095) [0.2500, 0.5000, 0.5000]
  PeriodicSite: Rh (4.5284, 1.5095, 1.5095) [0.7500, 0.5000, 0.5000],
  Structure Summary
  Lattice
      abc : 5.086717 2.548028 2.548028
   angles : 90.0 90.0 90.0
   volume : 33.02523894343128
        A : 5.086717 0.0 0.0
        B : 0.0 2.548028 0.0
        C : 0.0 0.0 2.548028
  PeriodicSite: Rh (1.2717, 1.2740, 1.2740) [0.2500, 0.5000, 0.5000]
  PeriodicSite: Rh (3.8150, 1.2740, 1.2740) [0.7500, 0.5000, 0.5000]],
 'task_ids': [],
 'deprecated_tasks': [],
 'calc_types': None,
 'last_updated': datetime.datetime(2021, 8, 10, 2, 26, 28, 356488),
 'created_at': datetime.datetime(2021, 8, 10, 2, 26, 28, 356489),
 'origins': None,
 'warnings': []}

EXCERCISE 1


EXCERCISE 2