Querying Data
An introduction on how to query for data with the Materials Project API client.
There are two main ways of querying Materials Project data. The first is through a specific Materials Project ID (e.g. mp-149), and the second is 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 a Materials Project ID use the generic get_data_by_id function:
1
with MPRester("your_api_key_here") as mpr:
2
doc = mpr.summary.get_data_by_id("mp-149")
Copied!
The above returns a MPDataEntry object with data accessible through its attributes. For example, the Material ID and formula can be obtained with:
1
mpid = doc.material_id
2
formula = doc.formula_pretty
Copied!
A list of available property fields can be obtained by examining one of these objects, or from the MPRester with:
1
list_of_available_fields = mpr.summary.available_fields
Copied!
To query summary data with property filters use the search function. Filters for each of the fields in available_fields can be passed to it, returning a list of MPDataEntry objects. 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.
1
with MPRester("your_api_key_here") as mpr:
2
docs = mpr.summary.search(elements=["Si", "O"],
3
band_gap=(0.5, 1.0))
Copied!
Note that by default ALL available property data within MPDataEntry 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:
1
with MPRester("your_api_key_here") as mpr:
2
docs = mpr.summary.search(elements=["Si", "O"],
3
band_gap=(0.5, 1.0),
4
fields=["material_id",
5
"band_gap",
6
"volume"])
Copied!
Now, only the material_id, band_gap, and volume attributes of the returned MPDataEntry objects will be populated. A list of available fields that were not requested will be returned in the fields_not_requested parameter.
1
example_doc = docs[0]
2
3
mpid = example_doc.material_id # a Materials Project ID
4
formula = example_doc.formula_pretty # a formula
5
volume = example_doc.volume # a volume
6
7
example_doc.fields_not_requested # list of unrequested fields
Copied!

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 get_data_by_id function can be used:
1
with MPRester("your_api_key_here") as mpr:
2
doc = mpr.materials.get_data_by_id("mp-149", fields=["initial_structures"])
3
4
initial_structures = doc.initial_structures
Copied!
Materials also has a search function that can be used with property filters:
1
with MPRester("your_api_key_here") as mpr:
2
docs = mpr.materials.search(elements=["Si", "O"],
3
band_gap=(0.5, 1.0),
4
fields=["initial_structures"])
5
6
example_doc = docs[0]
7
initial_structures = example_doc.initial_structures
Copied!
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 the get_data_by_id and search functions, 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 get_data_by_id and 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/client.py at main · materialsproject/api
GitHub
Generic get_data_by_id method.
api/summary.py at main · materialsproject/api
GitHub
Summary search method.
api/materials.py at main · materialsproject/api
GitHub
Materials search method.
Export as PDF
Copy link
Edit on GitHub