repository·main·Indexed 41 days ago
https://github.com/materialsproject/apiA Python-based interface and client (mp-api) for programmatically accessing and downloading data from the Materials Project database. It includes the ContribsClient for managing project metadata, querying contributions, and handling data components such as pymatgen structures, pandas DataFrames for tables, and file attachments.
The mp-api package provides the core client implementation for accessing the updated Materials Project API.
This repository contains the low-level client classes and methods. For high-level guides, tutorials, and comprehensive instructions on how to use this code to download and query the Materials Project database, refer to the official Materials Project Next-Gen Documentation.
When submitting or working with contributions, the client expects specific Python types for different components. If you are building contributions manually, ensure you use the correct types to avoid MPContribsClientError:
structures: Must use a pymatgen Structure object (or PmgStructure).tables: Must use a pandas.DataFrame or mp_api.client.contribs.Table.attachments: Must use a str (file path), pathlib.Path, or mp_api.client.contribs.Attachment object.By default, the client uses a document_model (typically a Pydantic BaseModel) to return data. This provides data validation and IDE auto-complete for available fields.
If you prefer working with raw dictionaries and want to bypass validation overhead, set use_document_model=False during initialization.
The CoreRester class implements a lazy-loading pattern for sub-resters. Instead of initializing all API endpoints at once, sub-resters (like materials, tasks, etc.) are only instantiated when they are first accessed as attributes.
This allows the main client to remain lightweight while providing a seamless interface to various specialized API endpoints.
To simplify usage, especially for heavy users, you can set the PMG_MAPI_KEY environment variable. When this variable is present, you can instantiate the client without passing an api_key argument explicitly.
export PMG_MAPI_KEY="your_api_key_here"
# Then in Python:
from mp_api.client.core.client import MPRester
mpr = MPRester()The _Rester class (and its subclasses) serves as the base for interacting with the Materials Project REST API. You can initialize a client by providing an api_key. If no key is provided, the client will automatically look for the PMG_MAPI_KEY environment variable.
Key initialization arguments:
api_key: Your API key from the Materials Project dashboard.endpoint: The API URL (defaults to https://api.materialsproject.org).use_document_model: If True (default), data is returned as validated Pydantic models. If False, data is returned as raw dictionaries. Setting this to False bypasses data validation and auto-complete.local_dataset_cache: The directory where full datasets are cached (defaults to mp_datasets in the user's home directory).force_renew: If True, overwrites existing local datasets.timeout: Request timeout in seconds.# Example initialization (assuming a subclass like MPRester is used)
client = MPRester(api_key="YOUR_API_KEY")
# Using the client as a context manager to ensure session closure
with MPRester(api_key="YOUR_API_KEY") as mpr:
# perform queries
passIf you encounter issues while using the mp-api client, you can seek help through the following channels:
The MPContribsClientError is raised during contribution submission or downloading when validation fails. Common causes include:
Structure for the structures component).include list in download_contributions that contains components not recognized by MPCC_SETTINGS.COMPONENTS.contributions, structures, tables, or attachments).'json' or 'csv').ignore_dupes is False and a duplicate MD5 digest is detected for a contribution.Use get_all_ids to retrieve a list of existing contribution IDs and component (Object) IDs. This method supports two formats via the fmt argument:
fmt="sets" (default): Returns a dictionary where each project maps to sets of IDs (e.g., ids, identifiers, and component-specific sets like structures or attachments).fmt="map": Returns a dictionary mapping identifiers to their corresponding contribution data and component details.Arguments:
include: A list of components to include in the response (e.g., ["structures", "tables"]).data_id_fields: A dictionary mapping projects to extra fields in data to be treated as ID fields.timeout: Timeout in seconds.# Get sets of IDs
ids_sets = client.get_all_ids(query={"project": "sandbox"}, include=["structures"], fmt="sets")
# Get a map of identifiers to contribution data
ids_map = client.get_all_ids(query={"project": "sandbox"}, include=["structures"], fmt="map")The get_data_by_id() method retrieves a specific document using its primary key (e.g., material_id, task_id).
Note: This method is deprecated. It is recommended to use the search() method instead by passing the ID as a keyword argument (e.g., client.search(material_ids="mp-123")).
Arguments:
document_id (str): The unique identifier for the document.fields (list[str] | None): A list of specific fields to return.# Deprecated way
doc = client.get_data_by_id("mp-123")
# Recommended way
docs = client.search(material_ids="mp-123")
doc = docs[0] if docs else NoneThe _query_delta_backed method retrieves data from S3 that is structured as a DeltaTable. It handles local caching of the dataset to the local_dataset_cache directory.
Arguments:
bucket: S3 OpenData bucket.prefix: S3 object prefix.access_controlled: Whether the table has access-controlled data (requires specific permissions).versioned: Whether the table is partitioned by database version.timeout: Timeout for getting access-controlled groups.label: A label for the table in the QueryBuilder.Returns:
A dictionary containing a MPDataset object in the data key.