mp_api.client.routes.materials.electronic_structure.ElectronicStructureRester

class mp_api.client.routes.materials.electronic_structure.ElectronicStructureRester(api_key: str | None = None, endpoint: str | None = None, include_user_agent: bool = True, use_document_model: bool = True, session: requests.Session | None = None, headers: dict | None = None, mute_progress_bars: bool = False, db_version: str | None = None, local_dataset_cache: str | os.PathLike = PosixPath('/home/runner/mp_datasets'), force_renew: bool = False, query_builder: QueryBuilderWithCache | None = None, delta_catalog: DeltaCatalog | None = None, s3_client: Any | None = None, timeout: int = 20, **kwargs)[source]

Bases: BaseRester

Initialize the REST API helper class.

s3_client: boto3 S3 client object with which to connect to the object stores. timeout: Time in seconds to wait until a request timeout error is thrown

Parameters:

  • api_key – A String API key for accessing the MaterialsProject REST interface. Please obtain your API key at https://www.materialsproject.org/dashboard. If this is None, the code will check if there is a “PMG_MAPI_KEY” setting. If so, it will use that environment variable. This makes easier for heavy users to simply add this environment variable to their setups and MPRester can then be called without any arguments.

  • endpoint – Url of endpoint to access the MaterialsProject REST interface. Defaults to the standard Materials Project REST address at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface.

  • include_user_agent – If True, will include a user agent with the HTTP request including information on pymatgen and system version making the API request. This helps MP support pymatgen users, and is similar to what most web browsers send with each page request. Set to False to disable the user agent.

  • session – requests Session object with which to connect to the API, for advanced usage only.

  • use_document_model – If False, skip the creating the document model and return data as a dictionary. This can be simpler to work with but bypasses data validation and will not give auto-complete for available fields.

  • headers – Custom headers for localhost connections.

  • mute_progress_bars – Whether to disable progress bars.

  • db_version (str) – Database version to use for data read from S3 (full dataset downloads, phase diagrams), e.g. “2026.04.13”. Defaults to the version currently served by the API. REST queries always use the current database. See available_db_versions() on a rester for the versions available.

  • local_dataset_cache – Target directory for downloading full datasets. Defaults to ‘mp_datasets’ in the user’s home directory

  • force_renew – Option to overwrite existing local dataset

  • query_builder – DEPRECATED, use delta_catalog. Instance of QueryBuilderWithCache whose catalog is used for querying delta tables. NOTE: Must be a QueryBuilderWithCache, a deltalake.QueryBuilder will be ignored.

  • delta_catalog – Instance of DeltaCatalog to use for querying delta tables.

  • s3_client – boto3 S3 client object with which to connect to the object stores.

  • timeout – Time in seconds to wait until a request timeout error is thrown

  • **kwargs – access to legacy kwargs that may be in the process of being deprecated

__init__(api_key: str | None = None, endpoint: str | None = None, include_user_agent: bool = True, use_document_model: bool = True, session: requests.Session | None = None, headers: dict | None = None, mute_progress_bars: bool = False, db_version: str | None = None, local_dataset_cache: str | os.PathLike = PosixPath('/home/runner/mp_datasets'), force_renew: bool = False, query_builder: QueryBuilderWithCache | None = None, delta_catalog: DeltaCatalog | None = None, s3_client: Any | None = None, timeout: int = 20, **kwargs)

Initialize the REST API helper class.

s3_client: boto3 S3 client object with which to connect to the object stores. timeout: Time in seconds to wait until a request timeout error is thrown

Parameters:

  • api_key – A String API key for accessing the MaterialsProject REST interface. Please obtain your API key at https://www.materialsproject.org/dashboard. If this is None, the code will check if there is a “PMG_MAPI_KEY” setting. If so, it will use that environment variable. This makes easier for heavy users to simply add this environment variable to their setups and MPRester can then be called without any arguments.

  • endpoint – Url of endpoint to access the MaterialsProject REST interface. Defaults to the standard Materials Project REST address at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface.

  • include_user_agent – If True, will include a user agent with the HTTP request including information on pymatgen and system version making the API request. This helps MP support pymatgen users, and is similar to what most web browsers send with each page request. Set to False to disable the user agent.

  • session – requests Session object with which to connect to the API, for advanced usage only.

  • use_document_model – If False, skip the creating the document model and return data as a dictionary. This can be simpler to work with but bypasses data validation and will not give auto-complete for available fields.

  • headers – Custom headers for localhost connections.

  • mute_progress_bars – Whether to disable progress bars.

  • db_version (str) – Database version to use for data read from S3 (full dataset downloads, phase diagrams), e.g. “2026.04.13”. Defaults to the version currently served by the API. REST queries always use the current database. See available_db_versions() on a rester for the versions available.

  • local_dataset_cache – Target directory for downloading full datasets. Defaults to ‘mp_datasets’ in the user’s home directory

  • force_renew – Option to overwrite existing local dataset

  • query_builder – DEPRECATED, use delta_catalog. Instance of QueryBuilderWithCache whose catalog is used for querying delta tables. NOTE: Must be a QueryBuilderWithCache, a deltalake.QueryBuilder will be ignored.

  • delta_catalog – Instance of DeltaCatalog to use for querying delta tables.

  • s3_client – boto3 S3 client object with which to connect to the object stores.

  • timeout – Time in seconds to wait until a request timeout error is thrown

  • **kwargs – access to legacy kwargs that may be in the process of being deprecated

Methods

__init__([api_key, endpoint, ...])

Initialize the REST API helper class.

available_db_versions()

Database versions available for this collection's full dataset on S3.

count([criteria])

Return a count of total documents.

get_data_by_id(document_id[, fields])

search([material_ids, band_gap, chemsys, ...])

Query electronic structure docs using a variety of search criteria.

search_electronic_structure_docs(*args, **kwargs)

Deprecated.

Attributes

available_fields

delta_backed

delta_catalog

The DeltaCatalog used for delta-backed queries, created on first use.

primary_key

query_builder

use delta_catalog.

s3_client

session

suffix

document_model

alias of ElectronicStructureDoc

search_electronic_structure_docs(*args, **kwargs)[source]

Deprecated.

search(material_ids: str | list[str] | None = None, band_gap: tuple[float, float] | None = None, chemsys: str | list[str] | None = None, efermi: tuple[float, float] | None = None, elements: list[str] | None = None, exclude_elements: list[str] | None = None, formula: str | list[str] | None = None, is_gap_direct: bool | None = None, is_metal: bool | None = None, magnetic_ordering: Ordering | None = None, num_elements: tuple[int, int] | None = None, num_chunks: int | None = None, chunk_size: int = 1000, all_fields: bool = True, fields: list[str] | None = None, db_version: str | None = None)[source]

Query electronic structure docs using a variety of search criteria.

Parameters:

  • material_ids (str | list[str]) – A single Material ID string or list of strings (e.g., mp-149, [mp-149, mp-13]).

  • band_gap (tuple[float, float]) – Minimum and maximum band gap in eV to consider.

  • chemsys (str | list[str]) – A chemical system or list of chemical systems (e.g., Li-Fe-O, Si-*, [Si-O, Li-Fe-P]).

  • efermi (tuple[float, float]) – Minimum and maximum fermi energy in eV to consider.

  • elements (list[str]) – A list of elements.

  • exclude_elements (list[str]) – A list of elements to exclude.

  • formula (str | list[str]) – A formula including anonymized formula or wild cards (e.g., Fe2O3, ABO3, Si*). A list of chemical formulas can also be passed (e.g., [Fe2O3, ABO3]).

  • is_gap_direct (bool) – Whether the material has a direct band gap.

  • is_metal (bool) – Whether the material is considered a metal.

  • magnetic_ordering (Ordering) – Magnetic ordering of the material.

  • num_elements (tuple[int, int]) – Minimum and maximum number of elements to consider.

  • num_chunks (int) – Maximum number of chunks of data to yield. None will yield all possible.

  • chunk_size (int) – Number of data entries per chunk.

  • all_fields (bool) – Whether to return all fields in the document. Defaults to True.

  • fields (list[str]) – List of fields in ElectronicStructureDoc to return data for. Default is material_id and last_updated if all_fields is False.

  • db_version (str | None) – Database version to download when no filters are given (full dataset), e.g. “2026.04.13” or “latest”. Defaults to the rester’s version. See available_db_versions().

Returns:

([ElectronicStructureDoc]) List of electronic structure documents

available_db_versions() → list[str]

Database versions available for this collection’s full dataset on S3.

Read from the DeltaTable’s log, no data is downloaded. Any of these can be pinned with MPRester(db_version=…) to download that version of the dataset.

Returns:

sorted database versions, e.g. [“2026.04.13”, “2026.09.28”]

Return type:

list of str

Raises:

MPRestError – if this collection isn’t delta-backed, or its dataset isn’t partitioned by database version.

count(criteria: dict | None = None) → int

Return a count of total documents.

Parameters:

criteria (dict | None) – As in .search(). Defaults to None

Returns:

Count of total results

Return type:

int

property delta_catalog: DeltaCatalog

The DeltaCatalog used for delta-backed queries, created on first use.

property query_builder: QueryBuilderWithCache

use delta_catalog.

Type:

Deprecated