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
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.
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
Last modified 9mo ago