OPTIMADE Python tools
| Latest release | Build status | Activity |
|---|---|---|
  
|
   |
  
|
The aim of OPTIMADE is to develop a common API, compliant with the JSON:API 1.0 specification. This is to enable interoperability among databases that serve crystal structures and calculated properties of existing and hypothetical materials.
This repository contains a library of tools for implementing and consuming OPTIMADE APIs using Python:
- pydantic data models for all OPTIMADE entry types and endpoint responses, and a Lark EBNF grammar implementation for the OPTIMADE filter language.
- Adapters to map OPTIMADE data to and from many commonly used atomistic Python frameworks (e.g., pymatgen, ASE) and crystallographic file types (e.g., CIF), using the
optimade.adaptersmodule. - A configurable reference server implementation that can make use of either MongoDB or Elasticsearch database backends out-of-the-box, and is readily extensible to other backends. Try it out on the demo site! The OpenAPI schemas of the server are used to construct the OPTIMADE schemas site.
- An OPTIMADE client (
optimade-get) that can query multiple OPTIMADE providers concurrently with a given filter, at the command-line or from Python code. - A fuzzy API validator tool, which may be called from the shell (
optimade-validator) or used as a GitHub Action from optimade-validator-action; this validator is used to construct the providers dashboard.
Documentation
This document, guides, and the full module API documentation can be found online at https://optimade.org/optimade-python-tools. In particular, documentation of the OPTIMADE API response data models (implemented here with pydantic) can be found online under OPTIMADE Data Models.
The release history and changelog can be found in the changelog.
Installation
Detailed installation instructions for different use cases (e.g., using the library or running a server) can be found in the installation documentation.
The latest stable version of this package can be obtained from PyPI:
pip install optimade
The latest development version of this package can be obtained from the main branch of this repository:
git clone https://github.com/Materials-Consortia/optimade-python-tools
Supported OPTIMADE versions
Each release of the optimade package from this repository only targets one version of the OPTIMADE specification, summarised in the table below.
| OPTIMADE API version | optimade requirements |
|---|---|
| v1.0.0 | optimade<=0.12.9 |
| v1.1.0 | optimade>=0.16,<1.2 |
| v1.2.0 | optimade>=1.2.0 |
Contributing and Getting Help
All development of this package (bug reports, suggestions, feedback and pull requests) occurs in the optimade-python-tools GitHub repository. Contribution guidelines and tips for getting help can be found in the contributing notes.
How to cite
If you use this package to access or serve OPTIMADE data, we kindly request that you cite the following:
- Evans et al., Developments and applications of the OPTIMADE API for materials discovery, design, and data exchange, Digital Discovery, 3, 1509-1533 (2024) 10.1039/D4DD00039K
- Andersen et al., OPTIMADE, an API for exchanging materials data, Sci. Data 8, 217 (2021) 10.1038/s41597-021-00974-z
- Evans et al., optimade-python-tools: a Python library for serving and consuming materials data via OPTIMADE APIs. Journal of Open Source Software, 6(65), 3458 (2021) 10.21105/joss.03458
Links
- OPTIMADE Specification, the human-readable specification that this library is based on.
- optimade-validator-action, a GitHub action that can be used to validate implementations from a URL (using the validator from this repo).
- OpenAPI, the machine-readable format used to specify the OPTIMADE API in
openapi.jsonandindex_openapi.json. - Interactive documentation generated from
openapi.json(see also interactive JSON editor). - pydantic, the library used for generating the OpenAPI schema from Python models.
- FastAPI, the framework used for generating the reference implementation expressed by the
openapi.jsonspecification. - Lark, the library used to parse the filter language in OPTIMADE queries.
5 maintainers
Metadata
5 maintainers
Release files for optimade 1.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| optimade-1.5.0.tar.gz | 195.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| optimade-1.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 437.6 kB
Release files / optimade-1.5.0.tar.gz
| Download URL | optimade-1.5.0.tar.gz |
|---|---|
| Size | 195.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
11bbae6001fa7b936b0e9d1c9b6f9683d029d4bdbc39fdf89df4cd0eaa1c85fa
|
|
BLAKE2b-256 checksum How to use checksums |
0a1c48a18067d56113ce392bacaa638c04e4d158b95b0434fcbbc90c94fe6aff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 21, 2026.
Transparency logRelease files / optimade-1.5.0-py3-none-any.whl
| Download URL | optimade-1.5.0-py3-none-any.whl |
|---|---|
| Size | 242.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7f197dee08015b24226aa623e72af6534aaaedf19fe11517c4b71ff33696a541
|
|
BLAKE2b-256 checksum How to use checksums |
9a4d7d706fc0fca10ac1dafc84ce5bfe2435d57fa739ef64e53cd9cb73123092
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 21, 2026.
Transparency log
