Querying Data

An introduction on how to query for data with the Materials Project API client.
Materials Project data can be queried through a specific (list of) Materials Project ID(s), and/or through property filters (e.g. band gap less than 0.5 eV).
Most material property data is available as summary data for a specific material. To query summary data with Materials Project IDs the search method should be used:
with MPRester("your_api_key_here") as mpr:
    docs = mpr.summary.search(material_ids=["mp-149", "mp-13", "mp-22526"])
The above returns a list of MPDataDoc objects with data accessible through their attributes. For example, the Material ID and formula can be obtained for a particular document with:
example_doc = docs[0]
​
mpid = example_doc.material_id
formula = example_doc.formula_pretty
A list of available property fields can be obtained by examining one of these objects, or from the MPRester with:
list_of_available_fields = mpr.summary.available_fields
To query summary data with property filters use the search function as well. Filters for each of the fields in available_fields can be passed to it. For example, below is a query to find materials containing Si and O that have a band gap greater than 0.5 eV but less then 1.0 eV.
with MPRester("your_api_key_here") as mpr:
    docs = mpr.summary.search(elements=["Si", "O"], 
                              band_gap=(0.5, 1.0))
Note that by default ALL available property data within MPDataDoc objects will be populated. If one is only interested in a few properties, limiting what data is returned will speed up data retrieval. Pass a list of the fields you are interested in to fields to accomplish this. For example, if we were only interested in material_id, band_gap, and volume for the materials from the above query, we could instead use:
with MPRester("your_api_key_here") as mpr:
    docs = mpr.summary.search(elements=["Si", "O"], 
                              band_gap=(0.5, 1.0),
                              fields=["material_id", 
                                      "band_gap", 
                                      "volume"])
Now, only the material_id, band_gap, and volume attributes of the returned MPDataDoc objects will be populated. A list of available fields that were not requested will be returned in the fields_not_requested parameter.
example_doc = docs[0]
​
mpid = example_doc.material_id       # a Materials Project ID
formula = example_doc.formula_pretty # a formula
volume = example_doc.volume          # a volume
​
example_doc.fields_not_requested     # list of unrequested fields
Other Data 
Not all Materials Project data for a given material can be obtained from the summary API endpoint. To access the remaining data, other endpoints must be used. For a complete list of endpoints see the main API page on the website. 
For example, the initial_structures used in calculations producing data for a specific material can only be found in the materials endpoint. To obtain the initial_structures for mp-149, the same search function can be used:
with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.search(material_ids=["mp-149"], fields=["initial_structures"])
​
example_doc = docs[0]
initial_structures = example_doc.initial_structures
Below is another example which uses property filters:
with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.search(elements=["Si", "O"], 
                                band_gap=(0.5, 1.0),
                                fields=["initial_structures"])
                                              
example_doc = docs[0]
initial_structures = example_doc.initial_structures
The same querying procedure shown above can be applied to most endpoints. See advanced usage and examples for more information.
Convenience Functions
In addition to search function, there are a small number of top level convenience functions for frequently made queries. These aim to provide a simpler interface, and make use of search under the hood. A couple examples of common queries include obtaining the structure or density of states of a particular material. These convenience functions are illustrated in the examples section. 
Relevant Code Links
api/materials.py at main · materialsproject/api
GitHub
Materials search method
api/summary.py at main · materialsproject/api
GitHub
Summary search method
Getting Started
Examples
Last modified 9mo ago