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.
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.nomad-coe.eu/api/v1.0/saml/
is used to authenticate the user with the identity provider and to get access 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.nomad-coe.eu/api/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. In order to logout (or a new user login/authentication) the user has to use the https://encyclopedia.nomad-coe.eu/api/v1.0/saml/logout/
endpoint in browser.
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.nomad-coe.eu/api/v1.0/materials/3
* Trying 130.183.207.97...
* TCP_NODELAY set
* Connected to encyclopedia.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 /api/v1.0/materials/3 HTTP/1.1
> Host: encyclopedia.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.nomad-coe.eu/api/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.nomad-coe.eu/api/v1.0/materials/3
* Trying 130.183.207.97...
* TCP_NODELAY set
* Connected to encyclopedia.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 /api/v1.0/materials/3 HTTP/1.1
> Host: encyclopedia.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.nomad-coe.eu/api/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.nomad-coe.eu/api/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.nomad-coe.eu/api/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
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.nomad-coe.eu/api/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.nomad-coe.eu/api/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.nomad-coe.eu/api/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
- date
string
(optional) Example: lastcan 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
200
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
}
}
404
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
- property
string
(required) Example: material_nameThe name of material property for which the available values are needed
200
Headers
Content-Type: application/json
Body
{
"material_name": [
"Actinium",
"Aluminum",
"Antimony",
"Argon",
"Arsenic",
"Barium",
"Beryllium",
"Bismuth",
"Boron",
"Bromine",
"Cadmium",
"Calcium",
"Carbon",
"Cerium",
"Cesium",
...,
"Zirconium"
]
}
404
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
- 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: 2The page number to be shown
- per_page
number
(optional) Default: 25 Example: 15The maximum number of items shown on page
- pagination
string
(optional) Default: 'on' Example: offTo disable the pagination, will return all results in one page.
200
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
}
404
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
- material_id
number
(required)Unique identifier for the material resource acting on
200
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"
}
404
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.nomad-coe.eu/api/v1.0/materials/8?property=bravais_lattice
Example - Response
{
"bravais_lattice": "cF"
}
Example URI
- material_id
number
(required)Unique identifier for the resource acting on
- property
string
(optional)One of the property mentioned in the above list
200
Headers
Content-Type: application/json
Body
{
"bravais_lattice": "cF"
}
404
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
- material_id
number
(required)Unique identifier for the resource acting on
200
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
}
404
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.nomad-coe.eu/api/v1.0/materials/4768/calculations?page=1&per_page=25",
"last_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/materials/4768/calculations?page=18&per_page=25",
"next_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/materials/4768/calculations?page=6&per_page=25",
"page": 5,
"pages": 18,
"per_page": 25,
"prev_url": "https://encyclopedia.nomad-coe.eu/api/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
- page
number
(optional) Default: 1 Example: 2The page number to be shown
- per_page
number
(optional) Default: 25 Example: 15The maximum number of items shown on page
- pagination
string
(optional) Default: 'on' Example: offTo disable the pagination, will return all results in one page.
200
Headers
Content-Type: application/json
Body
{
"pages": {
"first_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/materials/4768/calculations?page=1&per_page=25",
"last_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/materials/4768/calculations?page=18&per_page=25",
"next_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/materials/4768/calculations?page=6&per_page=25",
"page": 5,
"pages": 18,
"per_page": 25,
"prev_url": "https://encyclopedia.nomad-coe.eu/api/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
}
404
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
- material_id
number
(required)Unique identifier for the resource acting on
200
Headers
Content-Type: application/json
Body
{
"pages": {
"first_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/resource?per_page=25&page=1",
"last_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/resource?per_page=25&page=4",
"next_url": "https://encyclopedia.nomad-coe.eu/api/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
}
404
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
- material_id
number
(required)Unique identifier for the resource acting on
- element_id
number
(required)Unique identifier for the resource acting on
200
Headers
Content-Type: application/json
Body
{
"id": 424499,
"label": 33,
"material": 29717,
"position": "(0.5,0.5,0)",
"wyckoff": "a"
}
404
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
- material_id
number
(required)Unique identifier for the resource acting on
200
Headers
Content-Type: application/json
Body
{
"pages": {
"first_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/resource?per_page=25&page=1",
"last_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/resource?per_page=25&page=4",
"next_url": "https://encyclopedia.nomad-coe.eu/api/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
}
404
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
- material_id
number
(required)Unique identifier for the resource acting on
- cell_id
number
(required)Unique identifier for the resource acting on
200
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
}
404
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
- material_id
number
(required)Unique identifier for the resource acting on
200
Headers
Content-Type: application/json
Body
{
"pages": {
"first_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/resource?per_page=25&page=1",
"last_url": "https://encyclopedia.nomad-coe.eu/api/v1.0/resource?per_page=25&page=4",
"next_url": "https://encyclopedia.nomad-coe.eu/api/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
}
404
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
- material_id
number
(required)Unique identifier for the material resource acting on
- calc_id
number
(required)Unique identifier for the calculation resource
200
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"
}
]
}
404
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.nomad-coe.eu/api/v1.0/materials/8/calculations/1959?property=code_name
Example - Response
{
"code_name": "VASP"
}
Example URI
- 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
200
Headers
Content-Type: application/json
Body
{
"mass_density": 8453.99503310654
}
404
Headers
Content-Type: application/json
Body
{
"error": "not found",
"message": "invalid resource URI",
"status": 404
}