Materials Project API Client

0.46.0 · active · verified Tue Apr 14

mp-api is the official Python client for the Materials Project API, providing programmatic access to the vast Materials Project database. It features the MPRester class for easy data retrieval and is actively maintained with frequent updates to align with the evolving API and new data methodologies.

Warnings

breaking The `mp-api` library is the successor to the legacy `MPRester` client previously embedded in `pymatgen`. Users of the old `pymatgen.matproj.rest.MPRester` should migrate to `from mp_api.client import MPRester` to access the latest API features and maintain compatibility.
Fix: Update your import statements and client instantiation to use `from mp_api.client import MPRester`. Ensure `mp-api` is installed and updated.
gotcha An API key is mandatory for using the Materials Project API client. Failing to provide a valid key, either as a direct argument to `MPRester` or via the `MP_API_KEY` environment variable, will result in authentication errors.
Fix: Obtain your API key from your Materials Project profile dashboard and set it as the `MP_API_KEY` environment variable or pass it directly to `MPRester("YOUR_API_KEY")`.
gotcha For heavy or high-volume API usage, it is recommended to notify the Materials Project team by emailing `heavy.api.use@materialsproject.org`. This helps them anticipate server load and can prevent potential rate-limiting or service interruptions.
Fix: Contact the Materials Project team if your API usage is expected to be extensive.
gotcha The Materials Project API and its underlying data models (`emmet-core`) are continuously evolving. While the `mp-api` client is designed to abstract away many changes, occasional discrepancies or unexpected behavior can arise, especially if comparing with direct REST API calls or when using older versions of related data model libraries.
Fix: Keep `mp-api` and related packages (e.g., `emmet-core` if used directly) updated. Consult the official Materials Project documentation and community forums for the latest updates and known issues.

Install

pip install mp-api Install stable version

Imports

MPRester
```
from mp_api.client import MPRester
```
The `mp-api` client replaces the legacy MPRester previously found in `pymatgen`. Users should migrate to the new import path for current functionality.

Quickstart

This quickstart demonstrates how to instantiate the `MPRester` client using an API key from an environment variable and retrieve basic summary information for a material. You need a Materials Project API key, obtainable from your profile dashboard, to run this example.

import os
from mp_api.client import MPRester

# Set your Materials Project API key as an environment variable
# Example: export MP_API_KEY="YOUR_API_KEY_HERE"
# You can find your API key on your Materials Project profile dashboard.

api_key = os.environ.get('MP_API_KEY', '')

if not api_key:
    print("Error: MP_API_KEY environment variable not set. Please set it to your Materials Project API key.")
else:
    try:
        with MPRester(api_key) as mpr:
            # Fetch summary data for silicon (material_id: mp-149)
            material_id = "mp-149"
            docs = mpr.materials.summary.search(material_ids=[material_id])
            if docs:
                print(f"Material ID: {docs[0].material_id}")
                print(f"Formula: {docs[0].formula_pretty}")
                print(f"Band gap: {docs[0].band_gap} eV")
            else:
                print(f"No data found for material ID: {material_id}")
    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →