Difference between revisions of "The Materials API"

From Wiki
Jump to: navigation, search
(materials (calculated information))
(materials (calculated information))
Line 77: Line 77:
# <nowiki>https://www.materialsproject.org/rest/v1/materials/Fe2O3/vasp</nowiki>: [[File:Fe2O3.txt]]
# <nowiki>https://www.materialsproject.org/rest/v1/materials/Fe2O3/vasp</nowiki>: [[File:Fe2O3.txt]]
# <nowiki>https://www.materialsproject.org/rest/v1/materials/Li-Fe-O/vasp</nowiki>: [[File:Li-Fe-O.txt]]
# <nowiki>https://www.materialsproject.org/rest/v1/materials/Li-Fe-O/vasp</nowiki>: [[File:Li-Fe-O.txt]]
# <nowiki>https://www.materialsproject.org/rest/v1/materials/Si/vasp/energy</nowiki> [[File:Si_energy.txt]]
# <nowiki>https://www.materialsproject.org/rest/v1/materials/TiO2/vasp/energy</nowiki> [[File:TiO2_energy.txt]]
# <nowiki>https://www.materialsproject.org/rest/v1/materials/C/vasp/structure</nowiki> [[File:C_structure.txt]]
=== Operations ===  
=== Operations ===  

Revision as of 10:01, 30 August 2012

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


In the Materials Project, resources are generally packages of information about a material or an analysis (e.g., a reaction). Currently supported information types (v1 of the REST API) include the following:

  1. Materials - Standard calculated or experimental information about a material.
  2. Battery - Battery application specific information
  3. Reaction - Information about a reaction.


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. 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.



Write something about caps and daily limits.

API documentation

General URI Format

All URIs in the MAPI are of the general form

  1. The initial part of the URI (https://www.materialsproject.org/rest/v1/) is a preamble, specifying a https REST request. The v1 denotes version 1 of the MAPI, to provide flexibility to support multiple versions of the API in future.
  2. {request_type} specifies the kind of information or operation being requested. Currently supported request types include "materials", "battery", "reaction", "mpquery" and "api_check".
  3. {identifier} is an identifier for the specific information requested. Depending on the {request_type}, an identifier may or may not be necessary.
  4. {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}


materials (calculated information)

GET https://www.materialsproject.org/rest/v1/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., 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.

Example responses:

  1. https://www.materialsproject.org/rest/v1/materials/24972/vasp: File:24972.txt
  2. https://www.materialsproject.org/rest/v1/materials/Fe2O3/vasp: File:Fe2O3.txt
  3. https://www.materialsproject.org/rest/v1/materials/Li-Fe-O/vasp: File:Li-Fe-O.txt
  4. https://www.materialsproject.org/rest/v1/materials/TiO2/vasp/energy File:TiO2 energy.txt
  5. https://www.materialsproject.org/rest/v1/materials/C/vasp/structure File:C structure.txt



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