135 lines
3.0 KiB
Markdown
135 lines
3.0 KiB
Markdown
---
|
|
title: "Crystallography Open Database (COD) API"
|
|
task: ""
|
|
lineage_type: import
|
|
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/cod.md
|
|
upstream_sha: 9c9bd2e9
|
|
imported_at: 2026-06-26
|
|
prompt_class: prompt
|
|
upstream_changes: accepted
|
|
author: upstream
|
|
validated: false
|
|
---
|
|
|
|
# Crystallography Open Database (COD) API
|
|
|
|
## Base URL
|
|
|
|
```
|
|
https://www.crystallography.net/cod
|
|
```
|
|
|
|
## Authentication
|
|
|
|
**None required.** COD is fully open-access with no API key needed.
|
|
|
|
## Key Endpoints
|
|
|
|
### Search by formula
|
|
|
|
```
|
|
GET /result?formula=Fe2%20O3&format=json
|
|
```
|
|
|
|
Formula format uses spaces between elements: `Fe2 O3`, `Si O2`, `C6 H12 O6`. URL-encode spaces as `%20`.
|
|
|
|
### Search by elements
|
|
|
|
```
|
|
GET /result?el1=Fe&el2=O&format=json
|
|
```
|
|
|
|
Use `el1`, `el2`, `el3`, etc. for element filters. Use `nel=2` to restrict to exactly 2 elements.
|
|
|
|
### Search by cell parameters
|
|
|
|
```
|
|
GET /result?a_min=5.0&a_max=6.0&b_min=5.0&b_max=6.0&c_min=5.0&c_max=6.0&format=json
|
|
```
|
|
|
|
Cell parameter filters:
|
|
- `a_min`, `a_max` — a-axis length (Angstroms)
|
|
- `b_min`, `b_max` — b-axis length
|
|
- `c_min`, `c_max` — c-axis length
|
|
- `alpha_min`, `alpha_max` — alpha angle (degrees)
|
|
- `beta_min`, `beta_max` — beta angle
|
|
- `gamma_min`, `gamma_max` — gamma angle
|
|
- `vol_min`, `vol_max` — unit cell volume (A^3)
|
|
|
|
### Search by space group
|
|
|
|
```
|
|
GET /result?sg=F%20m%20-3%20m&format=json
|
|
```
|
|
|
|
### Search by text (author, journal, title)
|
|
|
|
```
|
|
GET /result?text=perovskite&format=json
|
|
```
|
|
|
|
### Combined search example
|
|
|
|
```
|
|
GET /result?el1=Ti&el2=O&nel=2&sg=P%2042/m%20n%20m&format=json
|
|
```
|
|
|
|
### Retrieve a specific CIF file
|
|
|
|
```
|
|
GET /1000000.cif
|
|
```
|
|
|
|
COD IDs are 7-digit integers. Append `.cif` for the crystallographic information file, or `.html` for the web page.
|
|
|
|
### Retrieve entry metadata as JSON
|
|
|
|
```
|
|
GET /result?id=1000000&format=json
|
|
```
|
|
|
|
### Output formats
|
|
|
|
- `format=json` — JSON array of matching entries
|
|
- `format=csv` — CSV output
|
|
- `format=lst` — list of COD IDs only
|
|
- Default (no format) — HTML page
|
|
|
|
## Response Format
|
|
|
|
```json
|
|
[
|
|
{
|
|
"file": "1526463",
|
|
"a": "4.759",
|
|
"b": "4.759",
|
|
"c": "12.992",
|
|
"alpha": "90",
|
|
"beta": "90",
|
|
"gamma": "120",
|
|
"vol": "254.94",
|
|
"sg": "R -3 c",
|
|
"formula": "Fe2 O3",
|
|
"title": "Refinement of the crystal structure of ...",
|
|
"journal": "Zeitschrift fuer Kristallographie",
|
|
"year": "1966",
|
|
"authors": "Blake, R.L.; et al."
|
|
}
|
|
]
|
|
```
|
|
|
|
The `file` field is the COD ID. Use it to fetch the CIF: `https://www.crystallography.net/cod/{file}.cif`
|
|
|
|
## Rate Limits
|
|
|
|
- No formal rate limits documented
|
|
- Be courteous: avoid bulk-downloading thousands of entries rapidly
|
|
- For bulk access, COD provides downloadable database dumps at https://www.crystallography.net/cod/archives/
|
|
|
|
## Notes
|
|
|
|
- COD contains ~500,000+ crystal structures from published literature
|
|
- All data is open-access under public domain / open licenses
|
|
- The search API returns metadata; use the CIF endpoint for full structural data
|
|
- Alternative access: MySQL database dumps and SVN access are available for bulk use
|