The Materials API

From Wiki
Revision as of 13:11, 29 August 2012 by Shyuep (talk | contribs)

Jump to: navigation, search

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

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

Accessing the MAPI

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 requests made via the MAPI must be https requests. 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/v1/1/vasp?API_KEY=YOUR_API_KEY

API documentation

Format of the URI

All URIs in the MAPI are of the general form

https://www.materialsproject.org/rest/v1/{request_type}/{identifier}/{parameters}