Back to top

NOMAD Encyclopedia REST API

API Authentication

Authenticate the user with Identity Service Provider and generate a token

GET/saml

For authenticating users into Encyclopedia API service, MPASS (http://www.mpass.fi/en/kehittajille/) is used as the identity provider. In order to integrate with MPASS, we implemented as part of our API the SAML 2.0 service provider roles. After implementing the service provider role, it was integrated with the MPASS identity provider, as well.

ssl_dhparam /home/nomadapp/ssl/dhparam.pem

A REST API service is supposed to be stateless, this means that the server must not store any session state and, consequently, must not issue session identifiers either. Every request is mandatory to contain all necessary information (data) to be properly authenticated/authorized. And also the authentication data should belong to the standard HTTP Authorization header. Taking these into consideration we provide the current endpoint. But also sending the username and password with every request is incovenient and is seen as a security risk even if we use HTTPS as transport layer. In this case, the client must have these credentials saved somewhere (unnencrypted) in order to use them within request. A good alternative to have the username and the password sent is to authenticate the user once and then generate a token which can be further used to access the API, in this way even if the token is stolen the user’s account is still safe.

The endpoint https://encyclopedia-api.nomad-coe.eu/v1.0/saml is used to authenticate the user with the identity provider and to get acccess to a token. A web browser should be used to access the mentioned URI. The user will be redirected to IdP service provider where the login take place. If the user doesn’t have an account yet, a new one can be created there, as well. After the user authentication with the IdP server is succesfull, the browser will redirect to https://encyclopedia-api.nomad-coe.eu/v1.0/saml/user/ where a few user details, including the access token can be found:

{
  "status": "Authenticated",
  "token": {
    "data": "eyJpYXQiOjE0OTIwMTM4MdeOsImFsZyI6IkhTMjU2IiwiZXdfDEoxNDkyMDE0NDM5fQ.eyJpZCI6Im5vbWFkIn0.Rr7vQz63lPwZeYsSg6k4JqwmZfmb4x1fRj-NMCfx55U",
    "expires_in": 86400
  },
  "user": {
    "email": "nomad@domain.com",
    "username": "nomad"
  }
}

The generated token will also have an expiration time embedded in it, it will expire after 24 hours, so, a new token (new user login/authentication) should be requested after this period of time.

After the user is authenticated with the IdP server and the token is received, the token can be used to send requests to Encyclopedia API. Here are a few simple examples using cURL and HTTPie (https://httpie.org/) command line clients:

cURL example:

  • without authentication token the client will get 401 UNAUTHORIZED:
$ curl -v https://encyclopedia-api.nomad-coe.eu/v1.0/materials/3
*   Trying 130.183.207.97...
* TCP_NODELAY set
* Connected to encyclopedia-api.nomad-coe.eu (130.183.207.97) port 443 (#0)
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
* SSL certificate verify ok.
> GET /v1.0/materials/3 HTTP/1.1
> Host: encyclopedia-api.nomad-coe.eu
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 401 UNAUTHORIZED
< Server: nginx/1.10.2
< Date: Fri, 28 Apr 2017 10:43:57 GMT
< Content-Type: application/json
< Content-Length: 170
< Connection: keep-alive
< WWW-Authenticate: Basic realm="Authentication Required"
< Strict-Transport-Security: max-age=31536000
<
{
  "error": "unauthorized",
  "login_url": "http://encyclopedia-api.nomad-coe.eu/v1.0/saml/",
  "message": "please send your authentication token",
  "status": 401
}
  • using the authentication token, the response is sent back to the client:
$ curl -v -u eyJpYXQiOjE0OTIwODc2NjgsImFsZyI6IkhTMjU2IiwiZdfdXhwIjoxNDkyMDg4MjY4fQ.eyJpZCI6Im5vbWFkIn0.3W_B_LHazQmIJ_5yL1hPJJv5fsEmedo6uwJbodscDWA: https://encyclopedia-api.nomad-coe.eu/v1.0/materials/3
*   Trying 130.183.207.97...
* TCP_NODELAY set
* Connected to encyclopedia-api.nomad-coe.eu (130.183.207.97) port 443 (#0)
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
* SSL certificate verify ok.
* Server auth using Basic with user 'eyJpYXQiOjE0OTIwODc2NjgsImFsZyI6IkhTMjU2IiwiZdfdXhwIjoxNDkyMDg4MjY4fQ.eyJpZCI6Im5vbWFkIn0.3W_B_LHazQmIJ_5yL1hPJJv5fsEmedo6uwJbodscDWA'
> GET /v1.0/materials/3 HTTP/1.1
> Host: encyclopedia-api.nomad-coe.eu
> Authorization: Basic ZXlKcFlYUWlPakUwT1RJd056QTJNelFzSW1Gc1p5STZJa2hUTWpVMklpd2laWGh3SWpveE5EazBOaddll5TmpNMGZRLmV5SnBaQ0k2SW5SbGMzUmZkRzlyWlc0aWZRLmVTTlE1aHBDa1ZrNEJBUm52XzVCaDBOVXdLdXZyQjVodkdEZkFMOFBuek06
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: nginx/1.10.2
< Date: Fri, 28 Apr 2017 10:47:28 GMT
< Content-Type: application/json
< Content-Length: 518
< Connection: keep-alive
< ETag: "2f8cd2b3865c5c7af8c41ffa4b3328db"
< Strict-Transport-Security: max-age=31536000
<
{
  "bravais_lattice": "cF",
  "cell_angles_string": "90.0/90.0/90.0",
  "crystal_system": "cubic",
  "formula": "Co2SbTa",
  "formula_reduced": "Co2SbTa",
  "has_free_wyckoff_parameters": false,
  "id": 3,
  "material_hash": "18c15abfbcd7deac192ba5413a359f9dee97feda1f2a173b59f43841d8bc1ee5f53e22375972174df9c673e97e3ca1025b480d25a18de57e3b756de7f4185083",
  "material_name": null,
  "periodicity": null,
  "point_group": "-43m",
  "space_group": 216,
  "structure_type": null,
  "system_type": "bulk"
}

HTTPie example (https://httpie.org/ other command line client similar to cURL but more user friendly):

  • without authentication token the client will get 401 UNAUTHORIZED:
$ http GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/3
HTTP/1.1 401 UNAUTHORIZED
Connection: keep-alive
Content-Length: 170
Content-Type: application/json
Date: Fri, 28 Apr 2017 10:52:46 GMT
Server: nginx/1.10.2
Strict-Transport-Security: max-age=31536000
WWW-Authenticate: Basic realm="Authentication Required"

{
    "error": "unauthorized",
    "login_url": "http://encyclopedia-api.nomad-coe.eu/v1.0/saml/",
    "message": "please send your authentication token",
    "status": 401
}
  • using the authentication token, the response is sent back to the client:
$ http --auth eyJpYXQiOjE0OTIwODc2NjgsImffFsZyI6IkhTMjU2IiwiZXhwIjoxNDkyMDeg4MjY4fQ.eyJpZCI6Im5vbWFkIn0.3W_B_gLHazQmIJ_5yL1hPJJv5fsEmedo6uwJbodscDWA: https://encyclopedia-api.nomad-coe.eu/v1.0/materials/3
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Fri, 28 Apr 2017 10:54:02 GMT
ETag: W/"2f8cd2b3865c5c7af8c41ffa4b3328db"
Server: nginx/1.10.2
Strict-Transport-Security: max-age=31536000
Transfer-Encoding: chunked

{
    "bravais_lattice": "cF",
    "cell_angles_string": "90.0/90.0/90.0",
    "crystal_system": "cubic",
    "formula": "Co2SbTa",
    "formula_reduced": "Co2SbTa",
    "has_free_wyckoff_parameters": false,
    "id": 3,
    "material_hash": "18c15abfbcd7deac192ba5413a359f9dee97feda1f2a173b59f43841d8bc1ee5f53e22375972174df9c673e97e3ca1025b480d25a18de57e3b756de7f4185083",
    "material_name": null,
    "periodicity": null,
    "point_group": "-43m",
    "space_group": 216,
    "structure_type": null,
    "system_type": "bulk"
}

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/saml

API Caching/ETag

Cache headers are an essential part of the HTTP specifications. Encyclopedia API makes use of caching in any place where is possible in order to increase scalability (an increased number of requests per seconds can be handled) and also to save bandwidth.

The HTTP specification allows the server to return different Cache-Control directives which control for how long, who can cache the response and under wich conditions the browser or any other intermediate caches can cache different individual responses. Each resource can define its caching policy via the Cache-Control header. Of course there are resources which the server will never cache (because we don’t want to have them cached), like sensitice data: passwords, credit cards, tokens, encryption keys, … So, in this case we use the following Cache-Control directives: 'private', 'no-cache', 'no-store', 'max-age=0'

In order to cache near-static data we use Entity Tags (ETags) which don’t rely on shared agreement on time. The ETag value is usually a hash (has to be unique and constant) calculated out of the bytes of the response body. ETags are used for two things – caching and conditional requests. Basically for each response the server provides an ETag header in the response which doesn’t change if the data available in the body response doesn’t change.

  • the server uses the ETag HTTP header to communicate a validation token.

  • the validation token enables efficient resource update checks: no data is transferred if the resource has not changed.

Let’s see a short example:

Here is shown the ETag header with a complete server response:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Thu, 27 Apr 2017 12:51:32 GMT
ETag →W/"2beabec698a4185261468d344cc61009"
Server: nginx/1.10.1

{
  "bravais_lattice": "tI",
  "cell_angles_string": "90.0/90.0/90.0",
  "crystal_system": "tetragonal",
  "formula": "In",
  "formula_reduced": "In",
  "has_free_wyckoff_parameters": false,
  "id": 5,
  "material_hash": "c611c411ea9dce16af56959a81b685f6203ac3a875a474789a5cb4cbf450e49c8dd3ea7769d6c802b5c1f675e08cfeb39f78d93e229a23641de2f5191c60e849",
  "material_name": "Indium",
  "periodicity": null,
  "point_group": "4/mmm",
  "space_group": 139,
  "structure_type": null,
  "system_type": "bulk"
}

Using an If-* header turns a standard GET request into a conditional GET. If the client sends a new request for the same URI resource, with the If-None-Match header, then the server will respond with Status: 304 Not Modified and an empty response body saving a lot of bandwidth.

curl -H 'If-None-Match: "2beabec698a4185261468d344cc61009"' https://encyclopedia-api.nomad-coe.eu/v1.0/materials/5
HTTP/1.1 304 Not Modified
ETag: "2beabec698a4185261468d344cc61009"

All HTTP requests that the API client makes are first routed to the client (browser) cache to check whether there is a valid cached response that can be used to fulfill the request. If there’s a match, the response is read from the cache, which eliminates both the network latency and the data costs that the transfer incurs.

Database Statistics

Retrieves statistics about materials and calculations available in our database

GET/dbstats{?date}

Example - Request:

https://encyclopedia-api.nomad-coe.eu/v1.0/dbstats?date=last

Example - Response

{
  "date": "21-04-2017",
  "id": 6,
  "summary": {
    "calculations": 1314077,
    "calculations_code_name": {
      "FHI-aims": 302,
      "Quantum Espresso": 138,
      "VASP": 1309857,
      "exciting": 3780
    },
    "calculations_functional_type": {
      "GGA": 1311032,
      "LDA": 3045
    },
    "calculations_with_band_structure": 244925,
    "calculations_with_dos": 271383,
    "calculations_with_fermi_surface": 0,
    "calculations_with_thermal_properties": 255,
    "materials": 511700,
    "materials_system_type": {
      "bulk": 511700
    },
    "materials_with_band_structure": 239653,
    "materials_with_dos": 255703,
    "materials_with_fermi_surface": 0,
    "materials_with_thermal_properties": 20
  }
}

Example using a date range - Request:

https://encyclopedia-api.nomad-coe.eu/v1.0/dbstats?between=20-04-2017&between=21-04-2017

Example using a date range - Response

[
  {
    "date": "20-04-2017",
    "id": 1,
    "summary": {
      "calculations": 1314077,
      "calculations_code_name": {
        "FHI-aims": 302,
        "Quantum Espresso": 138,
        "VASP": 1309857,
        "exciting": 3780
      },
      "calculations_functional_type": {
        "GGA": 1311032,
        "LDA": 3045
      },
      "calculations_with_band_structure": 244925,
      "calculations_with_dos": 271383,
      "calculations_with_fermi_surface": 0,
      "calculations_with_thermal_properties": 255,
      "materials": 511700,
      "materials_system_type": {
        "bulk": 511700
      },
      "materials_with_band_structure": 239653,
      "materials_with_dos": 255703,
      "materials_with_fermi_surface": 0,
      "materials_with_thermal_properties": 20
    }
  },
  {
    "date": "21-04-2017",
    "id": 6,
    "summary": {
      "calculations": 1314077,
      "calculations_code_name": {
        "FHI-aims": 302,
        "Quantum Espresso": 138,
        "VASP": 1309857,
        "exciting": 3780
      },
      "calculations_functional_type": {
        "GGA": 1311032,
        "LDA": 3045
      },
      "calculations_with_band_structure": 244925,
      "calculations_with_dos": 271383,
      "calculations_with_fermi_surface": 0,
      "calculations_with_thermal_properties": 255,
      "materials": 511700,
      "materials_system_type": {
        "bulk": 511700
      },
      "materials_with_band_structure": 239653,
      "materials_with_dos": 255703,
      "materials_with_fermi_surface": 0,
      "materials_with_thermal_properties": 20
    }
  }
]

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/dbstats?date=last
URI Parameters
HideShow
date
string (optional) Example: last

can be any of the following:

  • first - returns the statistics for the first available date

  • last - returns the statistics for the last available date

  • all - returns the statistics for all available dates

between
string (optional) 

returns the statistics for a date range

  • example: ?between=20-03-2017&between=23-03-2017 - will return statistics available for the specified date range
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "date": "20-04-2017",
  "id": 1,
  "summary": {
    "calculations": 1314077,
    "calculations_code_name": {
      "FHI-aims": 302,
      "Quantum Espresso": 138,
      "VASP": 1309857,
      "exciting": 3780
    },
    "calculations_functional_type": {
      "GGA": 1311032,
      "LDA": 3045
    },
    "calculations_with_band_structure": 244925,
    "calculations_with_dos": 271383,
    "calculations_with_fermi_surface": 0,
    "calculations_with_thermal_properties": 255,
    "materials": 511700,
    "materials_system_type": {
      "bulk": 511700
    },
    "materials_with_band_structure": 239653,
    "materials_with_dos": 255703,
    "materials_with_fermi_surface": 0,
    "materials_with_thermal_properties": 20
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Suggestions

Retrieves all possible values available in our database for a few material properties

GET/suggestions{?property}

This is an endpoint needed for “suggestions” feature implementation in GUI, for a few text fields. The available list of properties to access:

['material_name', 'structure_type', 'space_group', 'code_name']

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/suggestions?property=material_name
URI Parameters
HideShow
property
string (required) Example: material_name

The name of material property for which the available values are needed

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "material_name": [
    "Actinium",
    "Aluminum",
    "Antimony",
    "Argon",
    "Arsenic",
    "Barium",
    "Beryllium",
    "Bismuth",
    "Boron",
    "Bromine",
    "Cadmium",
    "Calcium",
    "Carbon",
    "Cerium",
    "Cesium",
    ...,
    "Zirconium"
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Material

Search for materials using a formula, by elements or by properties

POST/materials

Retrieves a list of materials (along with some specific properties) which match the formula, elements or the specified properties mentioned as filtering options in the json file sent as a POST request

Example of a complete POST body:

{
        "search_by": {
            "exclusive": "1",
            "element": "el1,el2,el3",
            "page": "1",
            "per_page": "5",
            "pagination": "off"
        },
        "material_name": ["Iron", "Cobalt"],
        "structure_type": ["Heusler / AlCu2Mn", "half-Heusler / AgAsMg"],
        "space_group": ["201", "203"],
        "system_type": ["bulk", "2D"],
        "crystal_system": ["monoclinic", "tetragonal", "trigonal", "orthorhombic", "cubic", "hexagonal" , "triclinic"],
        "band_gap": {
            "min": "2.8",
            "max": "4.6"
        },
        "band_gap_direct": "False",
        "has_band_structure": "True",
        "has_dos": "False",
        "has_fermi_surface": "True",
        "has_thermal_properties": "False",
        "functional_type": ["LDA", "hybrid-GGA", "GGA"],
        "basis_set_type": ["plane waves", "numeric AOs"],
        "code_name": ["FHI-aims", "VASP", "Quantum Espresso"],
        "mass_density": {
            "min": "8450",
            "max": "8500"
        }
    }

Each key-value pair in the above json represents a filtering option. The above json is searching for materials based on elements "el1,el2,el3" but if the user wants to search by formula, then "element": "el1,el2,el3" should be replaced with, for example, "formula": "PRhY" in the above json.

There is also possible to search without having any formula/element, just by properties. Here is a POSTed json example:

{
    "search_by": {
    },
    "functional_type": ["GGA"],
    "has_dos": "True",
    "system_type": ["bulk"]
}

The most minimal json POSTed should be:

{
    "search_by": {}
}

which will return basically all materials, paginated, having 25 items per page. Example returned json:

{
  "pages": {
    "page": 1,
    "pages": 169,
    "per_page": 25,
    "total": 4217
  },
  "results": [
      {
          ...
      },
      {
          ...
      }
  ],
  "total_results": 4217
}

Example URI

POST https://encyclopedia-api.nomad-coe.eu/v1.0/materials
URI Parameters
HideShow
formula
string (optional) Example: "H2O"

Formula specified by user to be part of the material

element
string (optional) Example: "el1,el2,el3"

Elements to search for

exclusive
number (optional) Default: 1 Example: "1"

Type of search: exclusive (“1”) or inclusive (“0”)

page
number (optional) Default: 1 Example: 2

The page number to be shown

per_page
number (optional) Default: 25 Example: 15

The maximum number of items shown on page

pagination
string (optional) Default: 'on' Example: off

To disable the pagination, will return all results in one page.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pages": {
    "page": 1,
    "pages": 9,
    "per_page": 15,
    "total": 124
  },
  "results": [
    {
      "calculations_list_matching_criteria": [
        444965,
        445045
      ],
      "formula": "Pr2Rh4",
      "formula_reduced": "PrRh2",
      "id": 139695,
      "material_name": "Praseodymium Rhodium",
      "nr_of_calculations": 2,
      "nr_of_calculations_matching_criteria": 2,
      "space_group": 227,
      "structure_type": "Cu2Mg (Cubic Laves)",
      "system_type": "bulk"
    },
    {
      "calculations_list_matching_criteria": [
        276613,
        277229,
        277348
      ],
      "formula": "PrRh",
      "formula_reduced": "PrRh",
      "id": 86661,
      "material_name": "Praseodymium Rhodium",
      "nr_of_calculations": 3,
      "nr_of_calculations_matching_criteria": 3,
      "space_group": 221,
      "structure_type": "ClCs",
      "system_type": "bulk"
    },
    {
      "calculations_list_matching_criteria": [
        248178,
        249235
      ],
      "formula": "PrRh",
      "formula_reduced": "PrRh",
      "id": 77848,
      "material_name": "Praseodymium Rhodium",
      "nr_of_calculations": 2,
      "nr_of_calculations_matching_criteria": 2,
      "space_group": 166,
      "structure_type": "CuPt",
      "system_type": "bulk"
    }
  ],
  "total_results": 124
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Retrieves properties of a specific material

GET/materials/{material_id}

Retrieves properties of a specific material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the material resource acting on

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "bravais_lattice": "tI",
  "cell_angles_string": "90.0/90.0/90.0",
  "crystal_system": "tetragonal",
  "formula": "GaMn2",
  "formula_reduced": "GaMn2",
  "has_free_wyckoff_parameters": true,
  "id": 4547,
  "material_hash": "8ac64fb9b8a4116c7f39c286b5e86a4ff1f9b3bf1ae28733a42f0bb902e139416a3a4fbba16af57a7a7d04e01dc8edd0770e9440336f4eb048c3d4718364078c",
  "material_name": "Gallium Manganese",
  "periodicity": null,
  "point_group": "4/mmm",
  "space_group": 139,
  "structure_type": "MoSi2",
  "system_type": "bulk"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Retrieves just one property for a specific material

GET/materials/{material_id}{?property}

In order to request just a single property of that material and not all of them, the property parameter should be used with a value from the following list:

['id', 'material_name', 'periodicity', 'formula', 'formula_reduced', 'space_group',
'point_group', 'bravais_lattice', 'crystal_system', 'structure_type',
'system_type', 'cell_angles_string', 'has_free_wyckoff_parameters', 'material_hash']

Example - Request:

https://encyclopedia-api.nomad-coe.eu/v1.0/materials/8?property=bravais_lattice

Example - Response

{
  "bravais_lattice": "cF"
}

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id?property=
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

property
string (optional) 

One of the property mentioned in the above list

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "bravais_lattice": "cF"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Retrieves calculations groups for a specific material

GET/materials/{material_id}/groups

Retrieves a list containing all calculations groups for a specific material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/groups
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "groups": [
    {
        "calculations_list": [
            14519,
            14628,
            14649,
            14659,
            14693,
            222985,
            223044,
            223046
        ],
        "energy_minimum": -3.43566690399e-18,
        "group_eos_hash": "cf0b03803a43c118df3755dda650f35632f516fe76e45e0b46b9ac3be2f26236cade7ce45c90b3e0ce98c52c03e679c6dbbf04234717a8a808d93ab0c3f8c172",
        "group_type": "equation of state",
        "material_hash": "8ac64fb9b8a4116c7f39c286b5e86a4ff1f9b3bf1ae28733a42f0bb902e139416a3a4fbba16af57a7a7d04e01dc8edd0770e9440336f4eb048c3d4718364078c",
        "method_hash": "128a689504a59db4859b3207fd724bd0ef0cbde2a38928f6cf70f76fbd0136cadedbfb06626085757ced71b0806ef6f92821156f0b8845a6480226a682e2336c",
        "nr_of_calculations": 8,
        "representative_calculation_id": 222985
    },
    {
      ...
    },
    {
      ...
    }
  ],
  "total_groups": 3
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Pagination

GET/resource?per_page=15&page=1&pagination=off

Retrieves a list with a subset of items from corresponding “collection/resource” (materials, calculations, …) and show only a defined number of them

NOTE: Each collection (materials, calculations, …) will contain a similar block like this one, as part of their JSON response:

"pages": {
    "first_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=1&per_page=25",
    "last_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=18&per_page=25",
    "next_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=6&per_page=25",
    "page": 5,
    "pages": 18,
    "per_page": 25,
    "prev_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=4&per_page=25",
    "total": 447
}

If the number of returned items is smaller than per_page (there is just one page), the pages block will not be present. If the user wants to have all items on a single page the pagination=off can be used.

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=15&page=1&pagination=off
URI Parameters
HideShow
page
number (optional) Default: 1 Example: 2

The page number to be shown

per_page
number (optional) Default: 25 Example: 15

The maximum number of items shown on page

pagination
string (optional) Default: 'on' Example: off

To disable the pagination, will return all results in one page.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pages": {
    "first_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=1&per_page=25",
    "last_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=18&per_page=25",
    "next_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=6&per_page=25",
    "page": 5,
    "pages": 18,
    "per_page": 25,
    "prev_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/materials/4768/calculations?page=4&per_page=25",
    "total": 447
  },
  "results": [
    {
      "atomic_density": 8.37272850485876e+28,
      "band_gap": 0.0,
      "band_gap_direct": null,
      "basis_set_short_name": null,
      "basis_set_type": "numeric AOs",
      "brillouin_zone_json": {
          ...
      },
      "cell_volume": 1.19435378732237e-29,
      "code_name": "FHI-aims",
      "code_version": "071914_7",
      "core_electron_treatment": "full all electron",
      "energy": [
        {
          "calc": 599842,
          "e_kind": "Free E",
          "e_val": -5.57018606862e-15,
          "id": 1788234
        },
        {
          "calc": 599842,
          "e_kind": "Total E projected to T=0",
          "e_val": -5.57018575217e-15,
          "id": 1788233
        },
        {
          "calc": 599842,
          "e_kind": "Total E",
          "e_val": -5.57018543572e-15,
          "id": 1788232
        }
      ],
      "fermi_surface": null,
      "functional_long_name": "GGA_C_PBE+GGA_X_PBE",
      "functional_type": "GGA",
      "group_convergencetest_hash": "3e2476a5634520b387c1f2201f9f4034abf09d183a9f379f23d252bdb23be4be4b6c99991f9f8885a145f18f75fddc3f43c027fd7ac121307eb5e45dc51d863e",
      "group_eos_hash": "1169defb53e7ff18f599d1820bd2f341def3fcbae02b57f9020c5ac98438d2f57be0b8c4e63a68c40a64e076753b97c51a9143932feb6a9dbe0799f236e53d54",
      "gw_starting_point": "",
      "gw_type": "",
      "has_band_structure": false,
      "has_dos": false,
      "has_fermi_surface": false,
      "has_thermal_properties": false,
      "id": 599842,
      "is_curtarolo_path": false,
      "k_point_grid_description": null,
      "lattice_parameters": "(2.879968e-10,2.879968e-10,2.879968e-10,1.5707963267949,1.5707963267949,1.5707963267949)",
      "mainfile_uri": "nmd://RbklxLhTagDp-X5fgsQldUFwks8gD/data/pbe/tight/standard/atomic_zora/4/26_Fe/output.out",
      "mass_density": 7764.26514947456,
      "material": 4768,
      "method_hash": "6e87d51e4fc4ee7af7467317f42e54195d605e7c6c28047b8d1f2575719814719d06340392e0407713233677284bd151b028105d8a5c01d82ec267421aa83dd5",
      "pressure": 0.0,
      "pseudopotential_type": null,
      "repository_pid": null,
      "repository_upload_comment": "",
      "repository_uri": "nmd://some_repo_uri",
      "run_type": "single point",
      "scf_threshold": 1.0,
      "smearing": "(none,0)",
      "wyckoff_groups_json": [
        {
          "element": "Fe",
          "indices": [
            0,
            1
          ],
          "variables": {},
          "wyckoff_letter": "a"
        }
      ]
    }
    },
    {
      ...
    }
  ],
  "total_results": 447
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Element

Collection of elements for a specific material

GET/materials/{material_id}/elements

Retrieves a list of elements, and the total number of elements, which are part of the specific material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/elements
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pages": {
    "first_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=1",
    "last_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=4",
    "next_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=2",
    "page": 1,
    "per_page": 25,
    "prev_url": "null",
    "total": 100
  },
  "results": [
    {
      "id": 424494,
      "label": 13,
      "material": 29717,
      "position": "(0.33333333,0,0.30545394)",
      "wyckoff": "i"
    },
    {
      "id": 424495,
      "label": 13,
      "material": 29717,
      "position": "(0.16666667,0.5,0.69454606)",
      "wyckoff": "i"
    },
    {
      "id": 424496,
      "label": 33,
      "material": 29717,
      "position": "(0,0,0)",
      "wyckoff": "a"
    },
    {
      "id": 424497,
      "label": 13,
      "material": 29717,
      "position": "(0.83333333,0.5,0.30545394)",
      "wyckoff": "i"
    },
    {
      "id": 424498,
      "label": 13,
      "material": 29717,
      "position": "(0.66666667,0,0.69454606)",
      "wyckoff": "i"
    },
    {
      "id": 424499,
      "label": 33,
      "material": 29717,
      "position": "(0.5,0.5,0)",
      "wyckoff": "a"
    }
  ],
  "total_results": 100
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Retrieves a few properties for one element for a given material

GET/materials/{material_id}/elements/{element_id}

Retrieves a few properties for one element for a given material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/elements/element_id
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

element_id
number (required) 

Unique identifier for the resource acting on

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 424499,
  "label": 33,
  "material": 29717,
  "position": "(0.5,0.5,0)",
  "wyckoff": "a"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Cell

Retrieves the number of cells for a specific material

GET/materials/{material_id}/cells

Retrieves the number of cells for a specific material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/cells
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pages": {
    "first_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=1",
    "last_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=4",
    "next_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=2",
    "page": 1,
    "per_page": 25,
    "prev_url": "null",
    "total": 100
  },
  "results": [
    {
      "a": "(6.49551962e-10,0,0)",
      "b": "(0,3.75019e-10,0)",
      "c": "(2.95782595278347e-26,0,4.83049636e-10)",
      "id": 59433,
      "is_primitive": false,
      "material": 29717
    },
    {
      "a": "(3.24775981e-10,-1.875095e-10,0)",
      "b": "(3.24775981e-10,1.875095e-10,0)",
      "c": "(2.95782595278347e-26,0,4.83049636e-10)",
      "id": 59434,
      "is_primitive": true,
      "material": 29717
    }
  ],
  "total_results": 100
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Retrieves the parameters of one cell for a specific material

GET/materials/{material_id}/cells/{cell_id}

Retrieves the parameters of one cell for a specific material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/cells/cell_id
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

cell_id
number (required) 

Unique identifier for the resource acting on

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "a": "(3.24775981e-10,-1.875095e-10,0)",
  "b": "(3.24775981e-10,1.875095e-10,0)",
  "c": "(2.95782595278347e-26,0,4.83049636e-10)",
  "id": 59434,
  "is_primitive": true,
  "material": 29717
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Calc

Retrieves all calculations for a specific material

GET/materials/{material_id}/calculations

Retrieves all calculations for a specific material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/calculations
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pages": {
    "first_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=1",
    "last_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=4",
    "next_url": "https://encyclopedia-api.nomad-coe.eu/v1.0/resource?per_page=25&page=2",
    "page": 1,
    "per_page": 25,
    "prev_url": "null",
    "total": 100
  },
  "results": [
    {
        "atomic_density": 8.50413326690471e+28,
        "band_gap": 0.0,
        "band_gap_direct": null,
        "basis_set_short_name": null,
        "basis_set_type": "plane waves",
        "brillouin_zone_json": {
            ...
        },
        "cell_volume": 3.52769636345542e-29,
        "code_name": "VASP",
        "code_version": "4.6.35  3Apr08 complex  parallel LinuxIFC",
        "core_electron_treatment": "pseudopotential",
        "energy": [
            {
                "calc": 223127,
                "e_kind": "Total E projected to T=0",
                "e_val": -1.55661062949e-22,
                "id": 669373
            },
            {
                "calc": 223127,
                "e_kind": "Free E",
                "e_val": -3.43618128116e-18,
                "id": 669374
            },
            {
                "calc": 223127,
                "e_kind": "Total E",
                "e_val": -3.43612939467e-18,
                "id": 669375
            }
        ],
        "fermi_surface": null,
        "functional_long_name": "GGA_C_PBE+GGA_X_PBE",
        "functional_type": "GGA",
        "group_convergencetest_hash": "3a5599726d9203a27e8091cfa92e5023a7a3fd5481efac30fcfad853194d9b3cd9a2d9d203946c987e446e096acceac14ad7680ddf022665bb3301cdb7923dfd",
        "group_eos_hash": "6ca0de6f6ed277a3043b9203a00fecca127f9a50beabdbb9dcdf1dd17d66a5ecccaad575b8323b75ee92af21d9b0673471ebce43e998514cd857153e2c0ad7b1",
        "gw_starting_point": "",
        "gw_type": "",
        "has_band_structure": false,
        "has_dos": false,
        "has_fermi_surface": false,
        "has_thermal_properties": false,
        "id": 223127,
        "is_curtarolo_path": false,
        "k_point_grid_description": null,
        "lattice_parameters": "(2.801769e-10,2.801769e-10,8.98786502e-10,1.5707963267949,1.5707963267949,1.5707963267949)",
        "mainfile_uri": "nmd://RabBGeQ1h4RwN3V4JMgeA0iS0uiln/data/66/vasprun.xml.relax1",
        "mass_density": 8453.99503310654,
        "material": 4547,
        "method_hash": "128a689504a59db4859b3207fd724bd0ef0cbde2a38928f6cf70f76fbd0136cadedbfb06626085757ced71b0806ef6f92821156f0b8845a6480226a682e2336c",
        "pressure": 0.0,
        "pseudopotential_type": null,
        "repository_pid": null,
        "repository_upload_comment": "",
        "repository_uri": "nmd://some_repo_uri",
        "run_type": "geometry optimization",
        "scf_threshold": 1.0,
        "smearing": "(none,0)",
        "wyckoff_groups_json": [
            {
                "element": "Ga",
                "indices": [
                    0,
                    3
                ],
                "variables": {},
                "wyckoff_letter": "a"
            },
            {
                "element": "Mn",
                "indices": [
                    1,
                    2,
                    4,
                    5
                ],
                "variables": {
                    "z": 0.32393467
                },
                "wyckoff_letter": "e"
            }
        ]
    },
    {
      ...
    }
  ],
  "total_results": 100
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Retrieves properties of a calculation for a specific material

GET/materials/{material_id}/calculations/{calc_id}

Retrieves properties of a calculation for a specific material

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/calculations/calc_id
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the material resource acting on

calc_id
number (required) 

Unique identifier for the calculation resource

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "atomic_density": 8.50413326690471e+28,
    "band_gap": 0.0,
    "band_gap_direct": null,
    "basis_set_short_name": null,
    "basis_set_type": "plane waves",
    "brillouin_zone_json": {
        ...
    },
        "cell_volume": 3.52769636345542e-29,
        "code_name": "VASP",
        "code_version": "4.6.35  3Apr08 complex  parallel LinuxIFC",
        "core_electron_treatment": "pseudopotential",
        "diagram_data": [],
        "energy": [
            {
                "calc": 223127,
                "e_kind": "Total E projected to T=0",
                "e_val": -1.55661062949e-22,
                "id": 669373
            },
            {
                "calc": 223127,
                "e_kind": "Free E",
                "e_val": -3.43618128116e-18,
                "id": 669374
            },
            {
                "calc": 223127,
                "e_kind": "Total E",
                "e_val": -3.43612939467e-18,
                "id": 669375
            }
        ],
        "fermi_surface": null,
        "functional_long_name": "GGA_C_PBE+GGA_X_PBE",
        "functional_type": "GGA",
        "group_convergencetest_hash": "3a5599726d9203a27e8091cfa92e5023a7a3fd5481efac30fcfad853194d9b3cd9a2d9d203946c987e446e096acceac14ad7680ddf022665bb3301cdb7923dfd",
        "group_eos_hash": "6ca0de6f6ed277a3043b9203a00fecca127f9a50beabdbb9dcdf1dd17d66a5ecccaad575b8323b75ee92af21d9b0673471ebce43e998514cd857153e2c0ad7b1",
        "gw_starting_point": "",
        "gw_type": "",
        "id": 223127,
        "k_point_grid_description": null,
        "lattice_parameters": "(2.801769e-10,2.801769e-10,8.98786502e-10,1.5707963267949,1.5707963267949,1.5707963267949)",
        "mainfile_uri": "nmd://RabBGeQ1h4RwN3V4JMgeA0iS0uiln/data/66/vasprun.xml.relax1",
        "mass_density": 8453.99503310654,
        "material": 4547,
        "method_hash": "128a689504a59db4859b3207fd724bd0ef0cbde2a38928f6cf70f76fbd0136cadedbfb06626085757ced71b0806ef6f92821156f0b8845a6480226a682e2336c",
        "pressure": 0.0,
        "pseudopotential_type": null,
        "repository_pid": null,
        "repository_upload_comment": "",
        "repository_uri": "nmd://some_repo_uri",
        "run_type": "geometry optimization",
        "scf_threshold": 1.0,
        "smearing": "(none,0)",
        "wyckoff_groups_json": [
            {
                "element": "Ga",
                "indices": [
                    0,
                    3
                ],
                "variables": {},
                "wyckoff_letter": "a"
            },
            {
                "element": "Mn",
                "indices": [
                    1,
                    2,
                    4,
                    5
                ],
                "variables": {
                    "z": 0.32393467
                },
                "wyckoff_letter": "e"
            }
        ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Retrieves just a property of a calculation for a specific material

GET/materials/{material_id}/calculations/{calc_id}{?property}

Retrieves just a property of a calculation for a specific material

In order to request just a single property of that calculation, for the specific material, and not all of them, the property parameter should be used with a value from the following list:

['id', 'run_type', 'code_name', 'code_version', 'basis_set_type', 'mass_density', 'atomic_density',
'basis_set_quality_quantifier', 'core_electron_treatment', 'pseudopotential_description',
'functional_type', 'functional_long_name', 'band_gap', 'band_gap_direct',
'band_gap_lower_kpt', 'band_gap_upper_kpt', 'band_gap_lower_energy', 'band_gap_upper_energy',
'cell_volume', 'density', 'k_point_grid_description', 'lattice_parameters',
'pressure', 'smearing', 'fermi_surface', 'repository_pid', 'gw_type', 'gw_starting_point',
'repository_uri', 'is_curtarolo_path', 'brillouin_zone_json', 'mainfile_uri', 'upload_comment',
'method_hash', 'group_eos_hash', 'group_convergencetest_hash', 'src_filepath', ‘material_id',
'band_structure', 'phonon_dos', 'phonon_dispersion', 'specific_heat_cv',
'qha_bulk_modulus', 'qha_helmholtz_free_energy', 'qha_mass_density',
'qha_specific_heat_cv', 'qha_thermal_expansion', 'gw_spectral_function']

Example - Request:

https://encyclopedia-api.nomad-coe.eu/v1.0/materials/8/calculations/1959?property=code_name

Example - Response

{
  "code_name": "VASP"
}

Example URI

GET https://encyclopedia-api.nomad-coe.eu/v1.0/materials/material_id/calculations/calc_id?property=
URI Parameters
HideShow
material_id
number (required) 

Unique identifier for the resource acting on

calc_id
number (required) 

Unique identifier for the resource acting on

property
string (optional) 

One of the property mentioned in the above list

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "mass_density": 8453.99503310654
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "not found",
  "message": "invalid resource URI",
  "status": 404
}

Energy

Generated by aglio on 28 Apr 2017