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

[
  {
    "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