Difference between revisions of "The Materials API"
m (→materials (calculated materials data)) |
m (→materials (calculated materials data)) |
||
Line 75: | Line 75: | ||
GET <nowiki>https://www.materialsproject.org/rest/v2/materials/{material id, formula, or chemical system}/vasp/{property}</nowiki> | GET <nowiki>https://www.materialsproject.org/rest/v2/materials/{material id, formula, or chemical system}/vasp/{property}</nowiki> | ||
− | Obtain material information based on an identifier. The response is always a list of associative arrays, i.e., [ {key:value, ... }, {... }, ...]. The identifier can be a Materials Project material id (e.g., mp-1234), a formula, e.g. (Fe2O3), or a chemical system ("-" separated list of elemments, e.g., Li-Fe-O). Specifying a formula or chemical system will return information for all materials with that formula or in that chemical system respectively. Note that a chemical system includes all sub-systems, i.e., the Li-Fe-O chemical system will include all Li, Fe, O, | + | Obtain material information based on an identifier. The response is always a list of associative arrays, i.e., [ {key:value, ... }, {... }, ...]. The identifier can be a Materials Project material id (e.g., mp-1234), a formula, e.g. (Fe2O3), or a chemical system ("-" separated list of elemments, e.g., Li-Fe-O). Specifying a formula or chemical system will return information for all materials with that formula or in that chemical system respectively. Note that a chemical system includes all sub-systems, i.e., the Li-Fe-O chemical system will include all Li, Fe, O, Fe<sub>x</sub>O<sub>y</sub>, Li<sub>x</sub>O<sub>y</sub>, Li<sub>x</sub>Fe<sub>y</sub>, Li<sub>x</sub>Fe<sub>y</sub>O<sub>z</sub> compounds. |
A property may be specified to request a specific subset of information. If no property is specified, a set of typically useful properties is returned. The materials id is always returned as part of the response. Currently supported properties and their definitions are as follows: | A property may be specified to request a specific subset of information. If no property is specified, a set of typically useful properties is returned. The materials id is always returned as part of the response. Currently supported properties and their definitions are as follows: |
Revision as of 21:25, 18 April 2018
The Materials API (MAPI) is an open API for accessing Materials Project data based on REpresentational State Transfer (REST) principles. In a RESTful system, information is organized into resources, each of which is uniquely identified via a uniform resource identifier (URI).
While the MAPI is designed to be code base agnostic and can conceivably be used with any programming language supporting basic http requests, a convenient wrapper to MAPI has been implemented in the Python Materials Genomics (pymatgen) library to facilitate researchers in using the MAPI. Please see the #pymatgen wrapper section.
For a quick overview, please refer to the following slides.
For a comprehensive listing of all criteria available for advanced queries via the #mpquery endpoint, see this repository.
Resources
In the Materials Project, resources are generally packages of information about a material or an analysis (e.g., a reaction). Currently supported information types (v2 of the REST API) include the following:
- Materials - Standard calculated or experimental information about a material.
- Battery - Battery application specific information
- Reaction - Information about a reaction.
Authentication
SSL Encryption
All requests to the Materials API must be done over HTTPS. Non-secure http requests are not allowed and will result in a HTTP 403 (Forbidden) response.
API keys
To access the Materials API, you will need your API key, except for certain free queries that do not require a key. You can obtain your API key by logging into the Materials Project website, and going to www.materialsproject.org/profile. Your API key and a button to regenerate the key is provided at the top of the page.
Note that the API key effectively allows access to Materials Project data via your account. You should therefore make all efforts to keep it secret and under no circumstances should you share your API key with anyone. You will be held responsible for any violations conducted using your API key. Should anyone else require access to the MAPI, they should register for an account on the Materials Project and generate their own API keys.
All MP https requests must supply API key as:
- A x-api-key header, e.g., {‘X-API-KEY’: ‘YOUR_API_KEY’} (recommended method) or
- As a GET (e.g., ?API_KEY=YOUR_API_KEY) or POST variable, e.g., {‘API_KEY’: ‘YOUR_API_KEY’}
The following is an example of a full url requesting for information of the material with material id 1234 with the API key supplied as a GET variable.
- https://www.materialsproject.org/rest/v2/materials/mp-1234/vasp?API_KEY=YOUR_API_KEY
Security
As a security precaution against bots, queries requiring the API key are subject to a daily cap. That cap is currently 500 units of information. This cap can be lifted if necessary. If you need higher levels of access, please email [email protected] with the details of your request.
API documentation
General URI Format
All URIs in the MAPI are of the general form
- https://www.materialsproject.org/rest/v2/{request_type}[/{identifier}][/{parameters}]
- The initial part of the URI (https://www.materialsproject.org/rest/v2/) is a preamble, specifying a https REST request. The v2 denotes version 2 of the MAPI, to provide flexibility to support multiple versions of the API in future.
- {request_type} specifies the kind of information or operation being requested. Currently supported request types include "materials", "battery", "reaction", "mpquery" and "api_check".
- {identifier} is an identifier for the specific information requested. Depending on the {request_type}, an identifier may or may not be necessary.
- {parameters} - Some requests require additional parameters to be provided.
General Response Format
All responses from the Materials API are in the JavaScript Object Notation (JSON). XML is not supported currently. The responses generally are of the following form:
{ valid_response: true, version: { pymatgen: "2.2.0", db: "2012.07.09", rest: "1.0" }, created_at: "2012-08-29T05:21:51.232084", copyright: "Copyright 2012, The Materials Project", response: {response_content} }
Resources
materials (calculated materials data)
GET https://www.materialsproject.org/rest/v2/materials/{material id, formula, or chemical system}/vasp/{property}
Obtain material information based on an identifier. The response is always a list of associative arrays, i.e., [ {key:value, ... }, {... }, ...]. The identifier can be a Materials Project material id (e.g., mp-1234), a formula, e.g. (Fe2O3), or a chemical system ("-" separated list of elemments, e.g., Li-Fe-O). Specifying a formula or chemical system will return information for all materials with that formula or in that chemical system respectively. Note that a chemical system includes all sub-systems, i.e., the Li-Fe-O chemical system will include all Li, Fe, O, FexOy, LixOy, LixFey, LixFeyOz compounds.
A property may be specified to request a specific subset of information. If no property is specified, a set of typically useful properties is returned. The materials id is always returned as part of the response. Currently supported properties and their definitions are as follows:
Basic properties
- pretty_formula
- A nice formula where the element amounts are normalized
- unit_cell_formula
- The full explicit formula for the unit cell
- icsd_id
The Inorganic Crystal Structure Database id for the initial structure, if any.
- energy
- Calculated vasp energy for structure
- energy_per_atom
- Calculated vasp energy normalized to per atom in the unit cell
- volume
- Final relaxed volume of the material
- density
- Final relaxed density of the material
- nsites
- Number of sites in the unit cell
- elements
- A array of the elements in the material
- nelements
- The number of elements in the material
- spacegroup
- An associative array containing basic space group information.
- initial_structure
- The initial input structure for the calculation in the pymatgen json representation (see later section).
- final_structure
- The final relaxed structure in the pymatgen json representation (see later section).
- structure
- An alias for final_structure.
- cif
- A string containing the structure in the CIF format.
Thermodynamic properties
- formation_energy_per_atom
- Calculated formation energy from the elements normalized to per atom in the unit cell
- e_above_hull
- Calculated energy above convex hull for structure. Please see Phase Diagram Manual for the interpretation of this quantity.
Mechanical properties
- elasticity
- Mechanical properties in the elastic limit. Contains the full elastic tensor as well as derived properties, e.g. Poisson ratio and bulk (K) and shear (G) moduli. Consult our hierarchical documentation for the particular names of sub-keys.
- piezo
- Piezoelectric properties. Contains a tensor and derived properties. Again, consult our repository for the names of sub-keys.
- diel
- Dielectric properties. Contains a tensor (one each for total and electronic contribution) and derived properties, e.g. dielectric constant, refractive index, and recognized potential for ferroelectricity.
Calculation parameters
- is_hubbard
- A boolean indicating whether the structure was calculated using the Hubbard U extension to DFT
- hubbards
- An array of Hubbard U values, where applicable.
- is_compatible
- Whether this calculation is considered compatible under the GGA/GGA+U mixing scheme.
Electronic structure
- band_gap
- The calculated band gap
- dos
- The calculated density of states in the pymatgen json representation
- bandstructure
- The calculated band structure in the pymatgen json representation
Others
- entry
- This is a special property that returns a pymatgen ComputedEntry in the json representation. ComputedEntries are the basic unit for many structural and thermodynamic analyses in the pymatgen code base.
- total_magnetization
- total magnetic moment of the unit cell
Example responses:
- https://www.materialsproject.org/rest/v1/materials/24972/vasp: File:24972.txt
- https://www.materialsproject.org/rest/v1/materials/Fe2O3/vasp: File:Fe2O3.txt
- https://www.materialsproject.org/rest/v1/materials/Li-Fe-O/vasp: File:Li-Fe-O.txt
- https://www.materialsproject.org/rest/v1/materials/TiO2/vasp/energy File:TiO2 energy.txt
- https://www.materialsproject.org/rest/v1/materials/C/vasp/structure File:C structure.txt
materials (experimental data)
GET https://www.materialsproject.org/rest/v1/materials/{formula}/exp
Obtain experimental thermochemical information based on an formula. The response is always a list of associative arrays, i.e., [ {key:value, ... }, {... }, ...]. The associative arrays are pymatgen ThermoData objects in json representation.
Example response: https://www.materialsproject.org/rest/v1/materials/Fe2O3/exp: File:Fe2O3 exp.txt
tasks (detailed calculation data)
GET https://www.materialsproject.org/rest/v1/tasks/{task id}/{property}
Obtain information about a particular calculation based on a task id. The response is always a list of associative arrays, i.e., [ {key:value, ... }, {... }, ...].
A property may be specified to request a specific subset of information. If no property is specified, a set of typically useful properties is returned. The materials id is always returned as part of the response. Currently supported properties and their definitions are as follows:
Basic properties
- pretty_formula
- A nice formula where the element amounts are normalized
- unit_cell_formula
- The full explicit formula for the unit cell
- icsd_id
The Inorganic Crystal Structure Database id for the initial structure, if any.
- energy
- Calculated vasp energy for structure
- energy_per_atom
- Calculated vasp energy normalized to per atom in the unit cell
- volume
- Final relaxed volume of the material
- density
- Final relaxed density of the material
- nsites
- Number of sites in the unit cell
- elements
- A array of the elements in the material
- nelements
- The number of elements in the material
- initial_structure
- The initial input structure for the calculation in the pymatgen json representation (see later section).
- final_structure
- The final relaxed structure in the pymatgen json representation (see later section).
- structure
- An alias for final_structure.
Thermodynamic properties
- formation_energy_per_atom
- Calculated formation energy from the elements normalized to per atom in the unit cell
- e_above_hull
- Calculated energy above convex hull for structure. Please see Phase Diagram Manual for the interpretation of this quantity.
Calculation parameters
- is_hubbard
- A boolean indicating whether the structure was calculated using the Hubbard U extension to DFT
- hubbards
- An array of Hubbard U values, where applicable.
- is_compatible
- Whether this calculation is considered compatible under the GGA/GGA+U mixing scheme.
Electronic structure
- band_gap
- The calculated band gap
- dos
- The calculated density of states in the pymatgen json representation
- incar
- The INCAR parameters used for the run.
- kpoints
- The KPOINTS grid used for the run.
- potcar
- The pseudopotentials used for the run.
The responses are similar to the materials responses.
materials ids
GET https://www.materialsproject.org/rest/v1/materials/{formula or chemical system}/mids
Obtain the material ids relating to a formula or chemical system. The response is always a list of integers. This is one of the few types of queries that do not require an API key to be supplied.
Example response: https://www.materialsproject.org/rest/v1/materials/Fe2O3/mids https://www.materialsproject.org/rest/v1/materials/Fe-O/mids
mpquery
POST https://www.materialsproject.org/rest/v2/query
Advanced query using Mongo-like language for flexible queries on the Materials Project database. This provides the possibility of queries which would otherwise not be possible using the other simpler REST forms.
For example, a POST to mpquery with
{"criteria": "{'elements':{'$in':['Li', 'Na', 'K'], '$all': ['O']}, 'nelements':2}", "properties": "['formula', 'formation_energy_per_atom']"}
will return the formula and formation energy per atom of all Li, Na and K oxides. Supported keywords include the following: elements, nelements, nsites, formula, normalized_formula, energy, energy_per_atom, density, e_above_hull, formation_energy_per_atom, material_id. For a comprehensive listing of all criteria available, see this repository.
Operations
api_check
- GET or POST https://www.materialsproject.org/rest/v1/api_check
Checks if supplied API key (via GET, POST or x-api-key header) is a valid API key.
Example response:
{ valid_response: true, api_key_valid: true }
pymatgen wrapper
The Python Materials Genomics (pymatgen) library is the materials analysis library powering the Materials Project. Much of the output from the Materials API is generated using the pymatgen library as the backend, and indeed many of the responses are based on pymatgen's json serialization format. As such, pymatgen is the recommended, though not the only way to work with the Materials API.
The pymatgen library can be downloaded via the PyPi page at http://pypi.python.org/pypi/pymatgen. Please consult pymatgen's documentation if you run into any installation or usage issues.
Using the MAPI and pymatgen, researchers can perform sophisticated analyses utilizing the large amount of calculated and experimental data in the Materials Project + their own data. It is impossible to cover all possible use cases here, but a simple example will be provided here to illustrate the power of MAPI+pymatgen. More code snippets illustrating the use of pymatgen and the MAPI are available on Shyue Ping's GitHub gists at http://gist.github.com/shyuep (alternatively, search for "shyuep materials api" at http://gist.github.com).
Example: Generating phase diagrams
Using the MAPI + pymatgen, a researcher can construct a phase diagram for any chemical system with < 10 lines of code in a matter of minutes. For example, the following code:
from pymatgen.matproj.rest import MPRester from pymatgen.phasediagram.pdmaker import PhaseDiagram from pymatgen.phasediagram.plotter import PDPlotter #This initializes the REST adaptor. Put your own API key in. a = MPRester("YOUR_API_KEY") #Entries are the basic unit for thermodynamic and other analyses in pymatgen. #This gets all entries belonging to the Ca-C-O system. entries = a.get_entries_in_chemsys(['Ca', 'C', 'O']) #With entries, you can do many sophisticated analyses, #like creating phase diagrams. pd = PhaseDiagram(entries) plotter = PDPlotter(pd) plotter.show()
generates:
A slightly more advanced example, which employs pymatgen's borg package to assimilate data from a user's own calculations, combine that data with Materials Project data, and generating a completely new phase diagram is given in the Python Materials Genomics paper.