mp_api.client.routes.materials.materials.MaterialsRester

class mp_api.client.routes.materials.materials.MaterialsRester(api_key: str | None = None, endpoint: str = 'https://api.materialsproject.org/', include_user_agent: bool = True, session: requests.Session | None = None, s3_resource: Any | None = None, debug: bool = False, monty_decode: bool = True, use_document_model: bool = True, timeout: int = 20, headers: dict = None, mute_progress_bars: bool = False)[source]

Bases: BaseRester[MaterialsDoc]

Args: api_key (str): 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 (str): 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 (bool): 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. debug: if True, print the URL for every request monty_decode: Decode the data using monty into python objects 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. timeout: Time in seconds to wait until a request timeout error is thrown headers (dict): Custom headers for localhost connections.

__init__(api_key: str | None = None, endpoint: str = 'https://api.materialsproject.org/', include_user_agent: bool = True, session: requests.Session | None = None, s3_resource: Any | None = None, debug: bool = False, monty_decode: bool = True, use_document_model: bool = True, timeout: int = 20, headers: dict = None, mute_progress_bars: bool = False)

Args: api_key (str): 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 (str): 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 (bool): 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. debug: if True, print the URL for every request monty_decode: Decode the data using monty into python objects 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. timeout: Time in seconds to wait until a request timeout error is thrown headers (dict): Custom headers for localhost connections.

Methods

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

Args: api_key (str): A String API key for accessing the MaterialsProject REST interface.

count([criteria])

Return a count of total documents.

find_structure(filename_or_structure[, ...])

Finds matching structures from the Materials Project database.

get_data_by_id(document_id[, fields])

Query the endpoint for a single document.

get_structure_by_material_id(material_id[, ...])

Get a structure for a given Materials Project ID.

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

Query core material docs using a variety of search criteria.

search_material_docs(*args, **kwargs)

Deprecated.

Attributes

available_fields

primary_key

s3_resource

session

suffix

supports_versions

eos

materials

similarity

tasks

xas

fermi

grain_boundary

substrates

surface_properties

phonon

elasticity

thermo

dielectric

piezoelectric

magnetism

summary

robocrys

synthesis

insertion_electrodes

charge_density

electronic_structure

electronic_structure_bandstructure

electronic_structure_dos

oxidation_states

provenance

bonds

alloys

absorption

chemenv

document_model

alias of MaterialsDoc

get_structure_by_material_id(material_id: str, final: bool = True) → Structure | list[Structure][source]

Get a structure for a given Materials Project ID.

Parameters:

  • material_id (str) – Materials project ID

  • final (bool) – Whether to get the final structure, or the list of initial (pre-relaxation) structures. Defaults to True.

Returns:

Pymatgen structure object or list of

pymatgen structure objects.

Return type:

structure (Union[Structure, List[Structure]])

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

Deprecated.

search(material_ids: str | list[str] | None = None, chemsys: str | list[str] | None = None, crystal_system: CrystalSystem | None = None, density: tuple[float, float] | None = None, deprecated: bool | None = False, elements: list[str] | None = None, exclude_elements: list[str] | None = None, formula: str | list[str] | None = None, num_elements: tuple[int, int] | None = None, num_sites: tuple[int, int] | None = None, spacegroup_number: int | None = None, spacegroup_symbol: str | None = None, task_ids: list[str] | None = None, volume: tuple[float, float] | None = None, num_chunks: int | None = None, chunk_size: int = 1000, all_fields: bool = True, fields: list[str] | None = None)[source]

Query core material 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]).

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

  • crystal_system (CrystalSystem) – Crystal system of material.

  • density (Tuple[float,float]) – Minimum and maximum density to consider.

  • deprecated (bool) – Whether the material is tagged as deprecated.

  • 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]).

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

  • num_sites (Tuple[int,int]) – Minimum and maximum number of sites to consider.

  • spacegroup_number (int) – Space group number of material.

  • spacegroup_symbol (str) – Space group symbol of the material in international short symbol notation.

  • task_ids (List[str]) – List of Materials Project IDs to return data for.

  • volume (Tuple[float,float]) – Minimum and maximum volume 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 MaterialsCoreDoc to return data for. Default is material_id, last_updated, and formula_pretty if all_fields is False.

Returns:

([MaterialsDoc]) List of material documents

find_structure(filename_or_structure, ltol=0.2, stol=0.3, angle_tol=5.0, allow_multiple_results=False) → list[str] | str[source]

Finds matching structures from the Materials Project database.

Multiple results may be returned of “similar” structures based on distance using the pymatgen StructureMatcher algorithm, however only a single result should match with the same spacegroup, calculated to the default tolerances.

Parameters:

  • filename_or_structure – filename or Structure object

  • ltol – fractional length tolerance

  • stol – site tolerance

  • angle_tol – angle tolerance in degrees

  • allow_multiple_results – changes return type for either

  • material_ids (a single material_id or list of) –

Returns:

A matching material_id if one is found or list of results if allow_multiple_results is True

Raises:

MPRestError –

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

Return a count of total documents.

Parameters:

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

Returns:

Count of total results, or string indicating error

Return type:

(int | str)

get_data_by_id(document_id: str, fields: list[str] | None = None) → T

Query the endpoint for a single document.

Parameters:

  • document_id – the unique key for this kind of document, typically a task_id

  • fields – list of fields to return, by default will return all fields

Returns:

A single document.