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

Getting Started

Setting up the Materials Project API client.

PreviousUsing the APINextQuerying Data

Last updated 1 month ago

Was this helpful?

The MPRester is a Python client provided by the Materials Project for easily accessing data through its API. It can be found in the mp-api package, which can be installed most easily using pip:

pip install mp_api

As an alternative, the package can also be installed from :

git clone https://github.com/materialsproject/api
cd api
pip install -e .

An API key is needed in order to use the client. This is a unique key provided to each Materials Project account. Your API key can be found on your once logged in.

The MPRester client can then be imported and instantiated. It is preferred to use Python's with context manager for session management:

from mp_api.client import MPRester

# Option 1: Pass your API key directly as an argument.
with MPRester("your_api_key_here") as mpr:
    # do stuff with mpr...

# Option 2: Use the `MP_API_KEY` environment variable:
# export MP_API_KEY="your_api_key_here"
# Note: You can also configure your API key through pymatgen
with MPRester() as mpr:
    # do stuff with mpr ...

See the following sections for details on how to query different types of data. Documentation for MPRester's classes and methods can be found . The table below lists the available endpoints, their document models, and purpose.

Endpoint
Document Model
Purpose

/doi

DOIDoc

DOIs to reference specific materials on Materials Project.

/materials/absorption

AbsorptionDoc

Absorption spectrum based on frequency dependent dielectric function calculations.

/materials/alloys

AlloyPairDoc

Not yet documented.

/materials/bonds

BondingDoc

Structure graphs representing chemical bonds calculated from structure using near neighbor strategies as defined in pymatgen.

/materials/chemenv

ChemEnvDoc

Coordination environments based on cation-anion bonds computed for all unique cations in this structure. If no oxidation states are available, all bonds will be considered as a fall-back.

/materials/core

MaterialsDoc

Not yet documented.

/materials/dielectric

DielectricDoc

A dielectric property block

/materials/elasticity

ElasticityDoc

Not yet documented.

/materials/electronic_structure/bandstructure

ElectronicStructureDoc

Definition for a core Electronic Structure Document

/materials/electronic_structure/dos

ElectronicStructureDoc

Definition for a core Electronic Structure Document

/materials/electronic_structure

ElectronicStructureDoc

Definition for a core Electronic Structure Document

/materials/eos

EOSDoc

Fitted equations of state and energies and volumes used for fits.

/materials/grain_boundaries

GrainBoundaryDoc

Grain boundary energies, work of separation...

/materials/insertion_electrodes

InsertionElectrodeDoc

Insertion electrode

/materials/magnetism

MagnetismDoc

Magnetic data obtain from the calculated structure

/materials/oxidation_states

OxidationStateDoc

Oxidation states computed from the structure

/materials/phonon

PhononBSDOSDoc

Phonon band structures and density of states data.

/materials/piezoelectric

PiezoelectricDoc

A dielectric package block

/materials/provenance

ProvenanceDoc

A provenance property block

/materials/robocrys

RobocrystallogapherDoc

This document contains the descriptive data from robocrystallographer for a material: Structural features, mineral prototypes, dimensionality, ...

/materials/similarity

SimilarityDoc

Model for a document containing structure similarity data

/materials/substrates

SubstratesDoc

Possible growth substrates for a given material.

/materials/summary

SummaryDoc

Summary information about materials and their properties, useful for materials screening studies and searching.

/materials/surface_properties

SurfacePropDoc

Model for a document containing surface properties data

/materials/synthesis

SynthesisSearchResultModel

Model for a document containing synthesis recipes data and additional keyword search results

/materials/tasks

TaskDoc

Calculation-level details about VASP calculations that power Materials Project.

/materials/thermo

ThermoDoc

A thermo entry document

/materials/xas

XASDoc

Document describing a XAS Spectrum.

/molecules/assoc

MoleculeDoc

Not yet documented.

/molecules/bonding

MoleculeBondingDoc

Representation of molecular bonding.

/molecules/core

MoleculeDoc

Not yet documented.

/molecules/jcesr

MoleculesDoc

Molecules relevant to battery electrolytes.

/molecules/orbitals

OrbitalDoc

Not yet documented.

/molecules/partial_charges

PartialChargesDoc

Atomic partial charges of a molecule

/molecules/partial_spins

PartialSpinsDoc

Atomic partial charges of a molecule

/molecules/redox

RedoxDoc

Molecular properties related to reduction and oxidation, including vertical ionization energies and electron affinities, as well as reduction and oxidation potentials

/molecules/summary

MoleculeSummaryDoc

Summary information about molecules and their properties, useful for searching.

/molecules/tasks

TaskDocument

Definition of a Q-Chem task document

/molecules/thermo

MoleculeThermoDoc

Not yet documented.

/molecules/vibrations

VibrationDoc

Not yet documented.

its code repository
profile dashboard page
here