OPTIMADE-TO-SQL API Documentation

Overview

This server implements an OPTIMADE-compatible API for querying materials science data including crystal structures, phase diagrams, and physical properties. It translates OPTIMADE filter queries into SQL and returns structured JSON responses.

Base URL: /v1 — All data endpoints are relative to this path.

Endpoints

GET /versions

Discover supported major API versions (plain text CSV format).

GET /v1/info

Base info endpoint: server information, available endpoints, API version, provider, and license.

GET /v1/info/structures

Entry listing info for the structures entry type. structures

GET /v1/info/phasediagrams

Entry listing info for the phase diagrams entry type. phase diagrams

GET /v1/info/properties

Entry listing info for the physical properties entry type. properties

GET /v1/links

Links endpoint with one root link and child links to sub-databases (COD, MC3D, OQMD).

GET /v1/structures

Query crystal structure entries. Use the project query parameter to select a sub-database. structures

GET /v1/structures/{entry_id}

Fetch a single structure entry by ID (use project for non-default sub-databases). structures

GET /v1/phasediagrams

Query phase diagram entries. phase diagrams

GET /v1/properties

Query physical property entries. properties

GET /v1/extensions/ontology

Ontology index (report IDs, TTL/spec URLs). ontology

GET /v1/extensions/ontology/ttl

OWL Turtle (data/ontology/mpds-ontology.ttl). ontology

GET /v1/extensions/ontology/spec

JSON taxonomy (data/ontology/ontology-spec.json). ontology

Sub-databases: COD, MC3D, and OQMD structures are served through the same /v1/structures endpoint using the project query parameter, e.g. /v1/structures?project=cod. Per the OPTIMADE specification, entry type names must be valid identifiers (no slashes), so they are not exposed as separate top-level endpoints.

Query Parameters

Entry listing endpoints accept the following parameters:

Parameter	Type	Default	Description
`filter`	string	(empty)	OPTIMADE filter expression
`page_limit`	integer	100	Maximum number of results
`page_offset`	integer	0	Offset for pagination
`response_fields`	string	(empty)	Comma-delimited fields to include in the response (always includes `id`, `type`)
`project`	string	mpds-synthetic	Select structures sub-database: `mpds-synthetic`, `cod`, `mc3d`, `oqmd` (`/v1/structures` only)

Structures

Available filter fields for /v1/structures:

Field	Type	Description
`id`	string	Entry identifier
`immutable_id`	string	Immutable identifier
`nelements`	integer	Number of elements
`elements`	string	Element list (use with `HAS` operators)
`chemical_formula_descriptive`	string	Descriptive chemical formula
`chemical_formula_reduced`	string	Reduced chemical formula
`chemical_formula_anonymous`	string	Anonymous chemical formula
`dimension_types`	string	Dimension types
`lattice_vectors`	string	Lattice vectors
`cartesian_site_positions`	string	Cartesian site positions
`species_at_sites`	string	Species at sites
`species`	string	Species
`assemblies`	string	Assemblies
`structure_features`	string	Structure features
`last_modified`	datetime	Last modification timestamp
`elements_ratios`	string	Element ratios (from `attributes` JSON)
`_mcloud_mc3d_id`	string	MC3D identifier (use `IS KNOWN` to filter mc3d entries)

Set operators for elements

HAS ALL HAS ANY HAS ONLY

Example: elements HAS ALL "Si,O" — find structures containing both Si and O.

COD Structures cod

The Crystallography Open Database (COD) sub-database is a slave mirror of crystallography.net/cod. It replicates COD's MySQL data table with 534k+ crystal structures.

Query path: /v1/structures?project=cod — COD structures are served through the same structures endpoint using the project query parameter.

Available filter fields for /v1/structures?project=cod (selected fields):

Field	Type	Description
`id`	integer	COD entry ID (file number)
`_cod_a`, `_cod_b`, `_cod_c`	float	Lattice parameters (Å)
`_cod_alpha`, `_cod_beta`, `_cod_gamma`	float	Lattice angles (°)
`_cod_vol`	float	Unit cell volume (Å³)
`_cod_sg`	string	Space group symbol (Hermann-Mauguin)
`_cod_sghall`	string	Space group symbol (Hall)
`_cod_sgnumber`	integer	Space group number
`_cod_formula`	string	Summary chemical formula
`_cod_calcformula`	string	Calculated formula
`_cod_year`	integer	Year of publication
`_cod_journal`	string	Journal name
`_cod_authors`	string	Publication authors
`_cod_title`	string	Publication title
`_cod_doi`	string	DOI of the publication
`_cod_mineral`	string	Mineral name
`_cod_chemname`	string	IUPAC chemical name
`_cod_commonname`	string	Common compound name
`_cod_smiles`	string	SMILES descriptor
`_cod_method`	string	Structure determination method
`_cod_celltemp`	float	Cell measurement temperature (K)
`_cod_diffrtemp`	float	Diffraction temperature (K)
`_cod_wavelength`	float	Wavelength (Å)
`_cod_rall`, `_cod_robs`	float	R-factor values
`_cod_z`	integer	Number of formula units (Z)
`_cod_status`	string	Entry status: warnings, errors, retracted
`_cod_flags`	string	Entry flags (has coordinates, has disorder, has Fobs)

Full list: All 74 columns from COD's data table are available as _cod_* fields.

MC3D Structures mc3d

MC3D is a collection of DFT-calculated crystal structures from MPDS.

Query path: /v1/structures?project=mc3d — MC3D structures are served through the same structures endpoint using the project query parameter.

Available filter fields for /v1/structures?project=mc3d:

Field	Type	Description
`id`	integer	Entry identifier
`immutable_id`	string	Immutable UUID identifier
`nelements`	integer	Number of elements
`elements`	list	Element list (use with `HAS` operators)
`chemical_formula_descriptive`	string	Descriptive chemical formula
`chemical_formula_reduced`	string	Reduced chemical formula
`chemical_formula_anonymous`	string	Anonymous chemical formula
`nsites`	integer	Number of sites
`nperiodic_dimensions`	integer	Number of periodic dimensions
`last_modified`	datetime	Last modification timestamp
`_mcloud_mc3d_id`	string	MC3D identifier (e.g. mc3d-38464)
`_mcloud_source_db`	string	Source database name
`_mcloud_source_db_id`	string	Source database entry ID
`_mcloud_total_energy`	float	Total DFT energy (eV)
`_mcloud_cell_volume`	float	Unit cell volume (Å³)
`_mcloud_total_magnetization`	float	Total magnetization
`_mcloud_absolute_magnetization`	float	Absolute magnetization
`_mcloud_ctime`	string	Creation timestamp
`space_group_it_number`	integer	Space group IT number
`space_group_symbol_hall`	string	Space group Hall symbol
`space_group_symbol_hermann_mauguin`	string	Space group H-M symbol

OQMD Structures oqmd

The Open Quantum Materials Database (OQMD) is a database of DFT-calculated thermodynamic and structural properties of materials from Northwestern University.

Query path: /v1/structures?project=oqmd — OQMD structures are served through the same structures endpoint using the project query parameter.

Available filter fields for /v1/structures?project=oqmd:

Field	Type	Description
`id`	integer	Structure identifier
`nsites`	integer	Number of sites
`natoms`	integer	Number of atoms
`ntypes`	integer	Number of element types
`label`	string	Structure label
`measured`	boolean	Experimentally measured?
`entry_id`	integer	OQMD entry ID
`volume`	float	Unit cell volume (Å³)
`delta_e`	float	Formation energy (eV/atom)
`stability`	float	Distance from convex hull (eV/atom)
`band_gap`	float	Band gap (eV)
`total_energy`	float	Total DFT energy (eV)
`magnetic_moment`	float	Total magnetic moment (Μ_b)
`spacegroup`	integer	Space group ID
Joined fields (via oqmd_entries → oqmd_compositions)
`chemical_formula_descriptive`	string	Chemical formula (joined from compositions)
`chemical_formula_anonymous`	string	Anonymous formula (joined from compositions)
`nelements`	integer	Number of elements (joined from compositions)
`label`	string	Prototype/ICSD label (joined from entries)

Joins: OQMD structures are linked to entries via entry_id, and entries link to compositions via composition_id. Joined fields are automatically resolved with LEFT JOINs.

Phase Diagrams

Available filter fields for /v1/phasediagrams:

Field	Type	Description
`id`	string	Entry identifier
`naxes`	integer	Number of axes
`arity`	integer	Arity
`diatype`	string	Diagram type
`elements`	string	Chemical elements
`version`	string	Entry version
`object_type`	string	Object type
`title_a`	string	Title axis A
`title_b`	string	Title axis B

Physical Properties

Available filter fields for /v1/properties:

Field	Type	Description
`id`	integer	Entry identifier
`structure_id`	integer	Linked structure ID
`elements`	string	Element list
`nelements`	integer	Number of elements
`chemical_formula_descriptive`	string	Descriptive chemical formula
`chemical_formula_anonymous`	string	Anonymous chemical formula
`property_name`	string	Name of the physical property
`property_value`	float	Numeric value of the property
`property_unit`	string	Unit of the property
`conditions`	string	Measurement conditions (temperature, pressure)
`measurement_method`	string	Measurement method
`density`	float	Density value (kg/m³)
`melting_point`	float	Melting point value (K)
`lattice_parameter`	float	Lattice parameter (Å)
`band_gap`	float	Band gap value (eV)
`bulk_modulus`	float	Bulk modulus value (GPa)
`shear_modulus`	float	Shear modulus value (GPa)
`youngs_modulus`	float	Young's modulus value (GPa)
`poisson_ratio`	float	Poisson ratio (dimensionless)
`thermal_expansion`	float	Thermal expansion coefficient (1/K)
`electrical_conductivity`	float	Electrical conductivity (S/m)
`thermal_conductivity`	float	Thermal conductivity (W/(m·K))
`heat_capacity`	float	Heat capacity (J/(mol·K))
`magnetic_moment`	float	Magnetic moment (Bohr magnetons)
`cell_volume`	float	Unit cell volume (Å³)
`category`	string	Property category: elastic, thermal, electrical, magnetic, structural

Joins: Physical properties are linked to structures via structure_id. Structure fields can be used in filters through this relationship.

Ontology OWL

The MPDS OPTIMADE ontology is auto-generated from mpds-synthetic (OPTIMADE_PROPERTIES + ELEMENTS_DB) via mpds-generate-ontology. This server serves /v1/extensions/ontology/ttl (data/ontology/mpds-ontology.ttl) and /v1/extensions/ontology/spec (taxonomy JSON). Regenerate with python scripts/sync_ontology.py.

Downloads

OWL Turtle

Full ontology (mpds-ontology.ttl)

Taxonomy JSON

category_map and property hierarchy

Property Taxonomy

Category	Properties
structural	density, lattice_parameter, cell_volume
thermal	melting_point, thermal_expansion, thermal_conductivity, heat_capacity
elastic	bulk_modulus, shear_modulus, youngs_modulus, poisson_ratio
electrical	electrical_conductivity, band_gap
magnetic	magnetic_moment

Database mapping (API tables only)

The OPTIMADE API uses existing tables; ontology element individuals live in the TTL file, not separate SQL tables.

Column	OWL concept	Notes
`structures.elements`	:containsElement	TEXT[] — filter with `elements HAS Fe`
`physical_properties.elements`	:forComposition	TEXT[] composition
`physical_properties.conditions`	:MeasurementCondition	JSONB in-row (not a separate table)
`physical_properties.category`	subclass taxonomy	`elastic`, `thermal`, etc.

Filter Syntax

Filters follow the OPTIMADE filter format (v1.0.0). The basic syntax:

// Comparison operators
field < value
field <= value
field > value
field >= value
field = value
field != value

// String operators
field CONTAINS "substr"
field STARTS WITH "prefix"
field ENDS WITH "suffix"

// Set operators (for array/list fields)
elements HAS ALL "Si,O"
elements HAS ANY "Fe,Cu"
elements HAS ONLY "Si,O"

// Logical operators
condition1 AND condition2
condition1 OR  condition2
NOT condition

// Grouping
(nelements >= 2 AND nelements <= 5)

Value formats

Strings: enclosed in double quotes — "SiO2"
Numbers: plain integers or floats — 3, 2.5
Booleans: true or false

Query Examples

Structuresstructures

Structures with exactly 3 elements

nelements=3

Structures containing both Si and O

elements HAS ALL "Si,O"

Structures with band gap greater than 2.0 eV

band_gap > 2.0

Binary oxides (2 elements, contains O)

nelements=2 AND elements HAS ANY "O"

Formula containing "Fe3O4"

chemical_formula_descriptive CONTAINS "Fe3O4"

COD Structurescod

Structures published in year 2000

_cod_year=2000

Structures with space group number 14

_cod_sgnumber=14

Structures with lattice parameter a > 10 Å

_cod_a > 10.0

Structures from Acta Crystallographica

_cod_journal CONTAINS "Acta Crystallographica"

Retracted structures

_cod_status="retracted"

Mineral quartz

_cod_mineral="quartz"

MC3D Structuresmc3d

Structures containing Zn

elements HAS "Zn"

Specific MC3D entry by ID

_mcloud_mc3d_id="mc3d-38464"

Total energy below -10000 eV

_mcloud_total_energy < -10000

Space group 225 (Fm-3m)

space_group_it_number=225

OQMD Structuresoqmd

Structures with formation energy below 0 (stable)

delta_e < 0

Structures near the convex hull

stability < 0.1

Structures with volume greater than 100 Å³

volume > 100

Structures with band gap (semiconductors)

band_gap > 0

Magnetic structures

magnetic_moment > 0

By chemical formula (joined from compositions)

chemical_formula_descriptive CONTAINS "Fe"

By prototype name (joined from entries)

label CONTAINS "alpha"

Ternary compounds (3 elements, joined)

nelements=3

Phase Diagramsphasediagrams

Binary phase diagrams (2 axes)

naxes=2

Phase diagrams containing Fe and C

elements HAS ALL "Fe,C"

Phase diagrams of a specific type

diatype="binary"

Physical Propertiesproperties

All band gap measurements

property_name="band_gap"

Properties of compounds with 3 elements

nelements=3

Properties with value greater than 100

property_name="density" AND property_value > 100

Properties of compounds containing Si

elements HAS ANY "Si"

Young's modulus greater than 200 GPa

youngs_modulus > 200

Melting point between 500 K and 1500 K

melting_point >= 500 AND melting_point <= 1500

All elastic properties (ontology category filter) ontology

category="elastic"

← Back to query form