Materials Project Documentation
Return to materialsproject.org
  • Introduction
  • Frequently Asked Questions (FAQ)
    • Glossary of Terms
  • Changes and Updates
    • Database Versions
    • Website Changelog
  • Documentation Credit
  • Community
    • Getting Help
    • Getting Involved
      • Contributor Guide
      • Potential Collaborators
      • MP Community Software Ecosystem
    • Community Resources
    • Code of Conduct
  • Services
    • MPContribs
  • Methodology
    • Materials Methodology
      • Overview
      • Calculation Details
        • GGA/GGA+U Calculations
          • Parameters and Convergence
          • Hubbard U Values
          • Pseudo-potentials
        • r2SCAN Calculations
          • Parameters and Convergence
          • Pseudopotentials
      • Thermodynamic Stability
        • Energy Corrections
          • Anion and GGA/GGA+U Mixing
          • GGA/GGA+U/r2SCAN Mixing
        • Phase Diagrams (PDs)
        • Chemical Potential Diagrams (CPDs)
        • Finite Temperature Estimation
      • Electronic Structure
      • Phonon Dispersion
      • Diffraction Patterns
      • Aqueous Stability (Pourbaix)
      • Magnetic Properties
      • Elastic Constants
      • Piezoelectric Constants
      • Dielectric Constants
      • Equations of State (EOS)
      • X-ray Absorption Spectra (XAS)
      • Surface Energies
      • Grain Boundaries
      • Charge Density
      • Suggested Substrates
      • Related Materials
      • Optical absorption spectra
      • Alloys
    • Molecules Methodology
      • Overview
      • Calculation Details
      • Atomic Partial Charges
      • Atomic Partial Spins
      • Bonding
      • Metal Coordination and Binding
      • Natural Atomic and Molecular Orbitals
      • Redox and Electrochemical Properties
      • Molecular Thermodynamics
      • Vibrational Properties
      • Legacy Data
    • MOF Methodology
      • Calculation Parameters
        • DFT Parameters
        • Density Functionals
        • Pseudopotentials
        • DFT Workflow
  • Apps
    • Explore and Search Apps
      • Materials Explorer
        • Tutorial
      • Molecules Explorer
        • Tutorial
        • Legacy Data
      • Battery Explorer
        • Background
        • Tutorial
      • Synthesis Explorer
        • Background
        • Tutorial
      • Catalysis Explorer
        • Tutorial
      • MOF Explorer
        • Downloading the Data
        • Structure Details
          • QMOF IDs
          • Structure Sources
          • Finding MOFs by Common Name
          • Structural Fidelity
        • Property Definitions
          • SMILES, MOFid, and MOFkey
          • Pore Geometry
          • Topology
          • Electronic Structure
          • Population Analyses and Bond Orders
          • Symmetry
        • Version History
        • How to Cite
    • Analysis Apps
      • Phase Diagram
        • Background
        • Tutorials
        • FAQ
      • Pourbaix Diagram
        • Background
        • Tutorial
        • FAQ
      • Crystal Toolkit
        • Background
        • Tutorial
        • FAQ
      • Reaction Calculator
      • Interface Reactions
    • Characterization Apps
      • X-ray Absorption Spectra (XAS)
    • Explore Contributed Data
  • Downloading Data
    • How do I download the Materials Project database?
    • Using the API
      • Getting Started
      • Querying Data
      • Tips for Large Downloads
      • Examples
      • Advanced Usage
    • Differences between new and legacy API
    • Query and Download Contributed Data
    • AWS OpenData
  • Uploading Data
    • Contribute Data
  • Data Production
    • Data Workflows
    • Data Builders
Powered by GitBook
On this page
  • Other Data
  • Convenience Functions

Was this helpful?

Edit on GitHub
Export as PDF
  1. Downloading Data
  2. Using the API

Querying Data

An introduction on how to query for data with the Materials Project API client.

PreviousGetting StartedNextTips for Large Downloads

Last updated 1 month ago

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:

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.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.materials.summary.available_fields

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.

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(
        elements=["Si", "O"], band_gap=(0.5, 1.0)
    )

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 via search(). See the search() 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:

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.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

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"], num_sites=(0, 10),
        fields=["initial_structures"]
    )
                                              
example_doc = docs[0]
initial_structures = example_doc.initial_structures

Convenience Functions

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 .

client docs
endpoint
advanced usage
examples
examples section
summary data
the client docs
Advanced Usage
Materials Project ID(s)