Querying Data
An introduction on how to query for data with the Materials Project API client.
Last updated
Was this helpful?
An introduction on how to query for data with the Materials Project API client.
Last updated
Was this helpful?
Materials Project data can be queried through a specific (list of) , and/or through property filters (e.g. band gap less than 0.5 eV).
Most material property data is available as for a specific material. To query summary data with Materials Project IDs the search
method should be used:
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:
A list of available property fields can be obtained by examining one of these objects, or from the MPRester
with:
To query summary data with property filters use the search
function as well. 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
.
NOTE: The
available_fields
attribute is meant to refer to the data available from the endpoint, not necessarily which fields you can use to query that data viasearch()
. See thesearch()
docstrings for supported arguments. The section on might be helpful here, too.
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:
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.
Below is another example which uses property filters:
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. Consult the for a complete list of available endpoints/routes.
For example, the initial_structures
used in calculations producing data for a specific material can only be found in the materials
. To obtain the initial_structures
for mp-149
, the same search
function can be used:
The same querying procedure shown above can be applied to most endpoints. See and 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 .