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

Was this helpful?

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

Tips for Large Downloads

Tips for downloading large data sets from the API

The Materials Project API imposes rate limits on requests starting at 25/second. Below are a few tips for downloading large datasets quickly without hitting the limit:

  1. To get data for multiple materials, pass query parameter values as lists where available. For example, avoid looping over material ID values and instead pass the materials as a list in the search method:

    with MPRester("your_api_key_here") as mpr:
        docs = mpr.materials.summary.search(
            material_ids=["mp-149", "mp-13", "mp-22526"]
        )
  2. Before requesting data, use the has_props key to find which materials have data for your desired property. One source of wasted queries occurs when data is requested for materials that are either nonexistent or do not contain the property of interest. You should instead first determine what materials have the data you are looking for. For example, below is a query to get all of the material ID values for entries that have dielectric and density of states data:

    with MPRester("your_api_key_here") as mpr:
        docs = mpr.materials.summary.search(
            has_props=["dielectric", "dos"], fields=["material_id"]
        )
  3. Restrict the data returned to the specific fields of interest, to the extent possible. This will help our server load and greatly speed up data retrieval. For example, if you are only interested in the material ID, volume, and list of elements you can pass those values to the fields argument:

    with MPRester("your_api_key_here") as mpr:
        docs = mpr.materials.summary.search(
            material_ids=["mp-149", "mp-13", "mp-22526"],
            fields=["material_id", "volume", "elements"]
        )
  4. For large, long-running, or frequently duplicated queries, we ask that you make a local copy and retrieve the data using the API only once. This will speed up your own analyses and also avoid unnecessary loads on the Materials Project servers. Additionally, we've optimized downloads of full collections such that they're often more efficient and faster than providing long lists of material_ids or fields. For instance,

    with MPRester(
        "your_api_key_here", monty_decode=False, use_document_model=False
    ) as mpr:
        docs = mpr.materials.summary.search()
        # save docs to file ...
PreviousQuerying DataNextExamples

Last updated 24 days ago

Was this helpful?

We are currently in the process of developing additional tools for users to download extremely large datasets more easily. If you have further questions, please consult for existing solutions and/or post a question specifying in detail the issue you are facing and listing the steps you have taken to try to resolve the issue.

our forum