When to Use This Skill
Use this skill when:
- Querying multiple materials databases through a unified API
- Building federated search across crystallographic databases
- Integrating with Materials Project, COD, OQMD, NOMAD, or AFLOW
- Implementing materials data interoperability
- Developing client applications for materials databases
- Building high-throughput materials discovery workflows
Overview
OPTIMADE (Open Databases Integration for Materials Design) is a REST API standard for materials databases. It provides unified access to crystal structures and properties across multiple databases.
Format/Schema Details
- RESTful API: Standard endpoints for data access
- Filter Syntax: URL-based query language for complex searches
- Entry Types: Structures, calculations, references
- Properties: Standardized property names and units
- Pagination: Cursor-based navigation of results
- Providers Registry: List of OPTIMADE-compliant databases
API Access
Base Endpoints
| Endpoint |
Description |
/structures |
Crystal structures |
/calculations |
Calculation entries |
/references |
Bibliographic references |
/info |
API information |
/links |
Related resources |
/info/structures |
Structure properties |
Major Providers
| Provider |
Base URL |
| Materials Project |
https://api.materialsproject.org/optimade/v1 |
| COD |
https://www.crystallography.net/cod/optimade/v1 |
| OQMD |
https://oqmd.org/optimade/v1 |
| NOMAD |
https://nomad-lab.eu/prod/v1/optimade |
| AFLOW |
https://aflow.org/api/optimade/v1 |
| JARVIS |
https://jarvis.nist.gov/optimade/v1 |
Query Examples
Basic Structure Query
import requests
# Query Materials Project via OPTIMADE
BASE_URL = "https://api.materialsproject.org/optimade/v1"
params = {
"filter": 'elements HAS "Si"',
"page_limit": 10
}
response = requests.get(f"{BASE_URL}/structures", params=params)
data = response.json()
for entry in data.get('data', [])[:5]:
print(f"ID: {entry['id']}")
print(f"Formula: {entry['attributes']['chemical_formula']}")
print(f"Elements: {entry['attributes']['elements']}")
Query Multiple Providers
import requests
PROVIDERS = {
"Materials Project": "https://api.materialsproject.org/optimade/v1",
"COD": "https://www.crystallography.net/cod/optimade/v1",
"OQMD": "https://oqmd.org/optimade/v1",
}
def query_all_providers(filter_str, limit=5):
"""Query multiple OPTIMADE providers"""
results = {}
for name, base_url in PROVIDERS.items():
try:
params = {
"filter": filter_str,
"page_limit": limit
}
response = requests.get(f"{base_url}/structures", params=params)
data = response.json()
results[name] = data.get('data', [])
print(f"{name}: {len(results[name])} results")
except Exception as e:
print(f"{name}: Error - {e}")
return results
# Usage
results = query_all_providers('chemical_formula = "SiO2"')
Python Client (optimade-python-tools)
Installation
pip install optimade
Basic Usage
from optimade.client import OptimadeClient
# Initialize client with specific provider
client = OptimadeClient("https://api.materialsproject.org/optimade/v1")
# Query structures
structures = client.get_structures(
filter='elements HAS "Li" AND elements HAS "Co"',
page_limit=10
)
for struct in structures.data[:5]:
print(f"{struct.id}: {struct.attributes.chemical_formula}")
Multi-Provider Search
from optimade.client import OptimadeClient
# Query multiple providers at once
client = OptimadeClient() # Uses all known providers
results = client.get_structures(
filter='chemical_formula = "LiFePO4"',
page_limit=5
)
# Results grouped by provider
for provider, structures in results.items():
print(f"\n{provider}:")
for struct in structures:
print(f" {struct.id}: {struct.attributes.chemical_formula}")
Filter Syntax
| Operator |
Syntax |
Example |
| Equals |
= |
chemical_formula = "SiO2" |
| Not equals |
!= |
nelements != 1 |
| Greater than |
> |
nsites > 10 |
| Less than |
< |
nsites < 100 |
| Greater or equal |
>= |
nsites >= 10 |
| Less or equal |
<= |
nsites <= 100 |
| Contains |
HAS |
elements HAS "Si" |
| Contains all |
HAS ALL |
elements HAS ALL "Si","O" |
| Contains any |
HAS ANY |
elements HAS ANY "Si","Ge" |
| Starts with |
STARTS WITH |
chemical_formula STARTS WITH "Li" |
| Ends with |
ENDS WITH |
chemical_formula ENDS WITH "O3" |
| Contains string |
CONTAINS |
chemical_formula CONTAINS "Fe" |
| AND |
AND |
elements HAS "Si" AND nsites > 10 |
| OR |
OR |
elements HAS "Fe" OR elements HAS "Co" |
| NOT |
NOT |
NOT elements HAS "H" |
Query Examples
Filter by Elements
import requests
BASE_URL = "https://api.materialsproject.org/optimade/v1"
# Compounds containing Si AND O
params = {
"filter": 'elements HAS ALL "Si","O"',
"page_limit": 10
}
response = requests.get(f"{BASE_URL}/structures", params=params)
data = response.json()
for entry in data['data']:
print(entry['attributes']['chemical_formula'])
Filter by Formula
# Exact formula match
params = {
"filter": 'chemical_formula = "LiFePO4"'
}
# Formula pattern
params = {
"filter": 'chemical_formula CONTAINS "Fe"'
}
# Formula starts with
params = {
"filter": 'chemical_formula STARTS WITH "Li"'
}
Filter by Properties
import requests
BASE_URL = "https://api.materialsproject.org/optimade/v1"
# Filter by number of sites
params = {
"filter": 'nsites >= 10 AND nsites <= 100',
"page_limit": 10
}
# Filter by crystal system (if available)
params = {
"filter": 'nsites > 5 AND nelements <= 3'
}
Complex Queries
import requests
BASE_URL = "https://api.materialsproject.org/optimade/v1"
# Multiple conditions
filter_query = '''
elements HAS ALL "Li","O" AND
nelements <= 4 AND
nsites <= 20 AND
NOT elements HAS "H"
'''
params = {
"filter": filter_query,
"page_limit": 20
}
response = requests.get(f"{BASE_URL}/structures", params=params)
data = response.json()
print(f"Found {data['meta'].get('data_returned', 'unknown')} structures")
Available Properties
| Property |
Description |
Type |
id |
Entry identifier |
string |
chemical_formula |
Formula |
string |
chemical_formula_reduced |
Reduced formula |
string |
elements |
Element symbols |
list |
nelements |
Number of elements |
integer |
nsites |
Number of sites |
integer |
lattice_vectors |
Cell vectors |
array |
cartesian_site_positions |
Atomic positions |
array |
species_at_sites |
Species labels |
list |
dimension_types |
Periodic directions |
list |
nperiodic_dimensions |
Periodic dimensions |
integer |
Pagination
import requests
def get_all_structures(base_url, filter_str, page_size=50):
"""Paginate through all results"""
all_data = []
page_offset = 0
while True:
params = {
"filter": filter_str,
"page_limit": page_size,
"page_offset": page_offset
}
response = requests.get(f"{base_url}/structures", params=params)
data = response.json()
entries = data.get('data', [])
all_data.extend(entries)
# Check for more pages
if len(entries) < page_size:
break
page_offset += page_size
# Safety limit
if page_offset > 1000:
print("Reached pagination limit")
break
return all_data
# Usage
structures = get_all_structures(
"https://api.materialsproject.org/optimade/v1",
'elements HAS "Si"'
)
print(f"Retrieved {len(structures)} structures")
Get Structure as pymatgen
from pymatgen.core import Structure
import requests
def get_pymatgen_structure(base_url, entry_id):
"""Get pymatgen Structure from OPTIMADE entry"""
response = requests.get(f"{base_url}/structures/{entry_id}")
entry = response.json()['data']
attrs = entry['attributes']
# Extract structure data
lattice_vectors = attrs['lattice_vectors']
positions = attrs['cartesian_site_positions']
species = attrs['species_at_sites']
# Create pymatgen Structure
structure = Structure(
lattice=lattice_vectors,
species=species,
coords=positions,
coords_are_cartesian=True
)
return structure
# Usage
structure = get_pymatgen_structure(
"https://api.materialsproject.org/optimade/v1",
"mp-149"
)
print(f"Formula: {structure.formula}")
print(f"Lattice: {structure.lattice}")
Provider Registry
import requests
# Get list of all OPTIMADE providers
response = requests.get("https://providers.optimade.org/v1/links")
providers = response.json()
print("Available OPTIMADE Providers:")
for provider in providers.get('data', []):
attrs = provider.get('attributes', {})
print(f" {attrs.get('name', 'Unknown')}: {attrs.get('base_url', 'N/A')}")
Response Format
{
"data": [
{
"id": "mp-149",
"type": "structures",
"attributes": {
"chemical_formula": "Si",
"elements": ["Si"],
"nelements": 1,
"nsites": 2,
"lattice_vectors": [[5.43, 0, 0], [0, 5.43, 0], [0, 0, 5.43]],
"cartesian_site_positions": [[0, 0, 0], [2.715, 2.715, 2.715]],
"species_at_sites": ["Si", "Si"]
}
}
],
"meta": {
"data_returned": 1,
"more_data_available": false
}
}
Resources