Skip to main content

PSDI OPTIMADE API

The OPTIMADE (Open Databases Integration for Materials Design) API is a standardized REST API specification that facilitates the interoperability of materials databases. It allows users to access and query data across multiple materials databases in a uniform manner, enabling efficient data sharing and integration.

Adopting OPTIMADE allows us to expose the data using a common API, making it easier for researchers and developers to search, retrieve, and analyze materials data from diverse sources without dealing with different data formats or query languages.

You can find a list of all the data providers who share their datasets through OPTIMADE endpoints in the OPTIMADE Data Providers resource theme in our What We Provide pages and on the OPTIMADE Consortium dashboard.

OPTIMADE endpoints​

Each data source exposed via OPTIMADE has its own base URL, for example https://pchprop-optimade.psdi.ac.uk.

The OPTIMADE endpoints are a set of subpaths under this base URL. According to the OPTIMADE specification, they are constructed as:

base_url/<major_version>/<endpoint_name>

For example, https://pchprop-optimade.psdi.ac.uk/v1/info.

Types of OPTIMADE endpoints​

In the OPTIMADE API, endpoints can be grouped into two main categories: informational endpoints and data endpoints.

Informational endpoints provide metadata about the API itself. The mandatory /info endpoint describes the implementation, including supported features. In addition, /info/<entry_type> endpoints (e.g. /info/structures) define the schema for each resource type, listing available fields and queryable properties.

Data endpoints provide access to materials data in a uniform format. The mandatory endpoints are /structures, /references, and /links. The /structures endpoint contains atomistic and crystallographic data, /references provides associated bibliographic information, and /links enables discovery of other OPTIMADE-compliant databases. All data endpoints support a standard query interface, including filtering, pagination, sorting, and field selection, ensuring consistent access across different providers.

There are also other optional endpoints. For more details, see the OPTIMADE specification.

Types of fields​

In the OPTIMADE API, fields can be broadly divided into standard fields and provider-specific fields.

Standard fields are defined by the OPTIMADE specification and are consistent across all compliant implementations. These include commonly used properties such as structural information, chemical composition and bibliographic data.

Provider-specific fields are custom extensions introduced by data providers to expose additional data that is not covered by the standard. To avoid naming conflicts and maintain clarity, the OPTIMADE specification requires that such fields use a unique prefix.

In this implementation, all custom fields use the _psdi_ prefix (e.g. _psdi_band_gap). This convention makes it clear which fields are specific to PSDI.

OPTIMADE index meta-database​

This is a provider-level registry of our OPTIMADE-exposed data sources, enabling users to discover all PSDI databases through a single entry point.

Our implementation is available at https://metadata.psdi.ac.uk/optimade-index-metadb/.

The index meta-database aggregates the different databases we expose via OPTIMADE and lists them through the /links endpoint. Each entry in /links corresponds to one of our data sources and includes its base URL and relevant metadata.

This allows users and client applications to query a single endpoint to discover all available PSDI OPTIMADE APIs, and then follow the provided links to access each database individually.

OPTIMADE server​

We deploy a dedicated OPTIMADE server for each data source using the reference implementation provided by OPTIMADE Python tools.

Validation of OPTIMADE endpoints​

We validate our OPTIMADE endpoints using the official GitHub Action provided by the OPTIMADE Consortium.

Tutorials​

We have created a tutorial on querying the OPTIMADE API. It assumes no prior knowledge of OPTIMADE and is available as Jupyter and Marimo notebooks.

You can also find additional OPTIMADE tutorial materials provided by the OPTIMADE Consortium.

About this page

If you would like to contribute content to the PSDI Knowledge Base or have feedback you would like to give on this guidance, please contact us.