Materials Project API

Base URL

https://api.materialsproject.org

Authentication

Requires a free API key. Register at https://materialsproject.org (free account).

All requests must include the API key header.

API Version

The current API is v2 (based on the mp-api Python client and the new MAPI endpoints). The legacy v1 REST API at https://www.materialsproject.org/rest/v2/ is deprecated.

Key Endpoints

Search materials by formula or elements

GET /materials/summary/?formula=Fe2O3&_fields=material_id,formula_pretty,band_gap,formation_energy_per_atom

GET /materials/summary/?elements=Si,O&_fields=material_id,formula_pretty,band_gap

Query parameters:

• formula — exact chemical formula (e.g., Fe2O3, SiO2)
• chemsys — chemical system, dash-separated (e.g., Fe-O, Li-Fe-P-O)
• elements — comma-separated elements that must be present
• band_gap_min / band_gap_max — filter by band gap (eV)
• is_stable — true to return only thermodynamically stable phases
• _fields — comma-separated list of fields to return
• _limit — max results (default 10, max 1000)
• _skip — offset for pagination

Get material by ID

GET /materials/summary/mp-149?_fields=material_id,formula_pretty,band_gap,formation_energy_per_atom,symmetry

Material IDs have the format mp-NNNNN (e.g., mp-149 for silicon).

Available fields (summary)

material_id, formula_pretty, formula_anonymous, chemsys, volume, density, density_atomic, symmetry, band_gap, cbm, vbm, is_gap_direct, is_metal, is_magnetic, ordering, total_magnetization, formation_energy_per_atom, energy_above_hull, is_stable, equilibrium_reaction_energy_per_atom, nsites, elements, nelements, composition, structure

Crystal structure

GET /materials/summary/mp-149?_fields=structure

Returns the structure as a pymatgen-compatible JSON dict with lattice parameters and atomic sites.

Elastic properties

GET /materials/elasticity/?material_id=mp-149&_fields=material_id,bulk_modulus,shear_modulus,elastic_tensor

Electronic structure (band structure / DOS)

GET /materials/electronic_structure/bandstructure/mp-149
GET /materials/electronic_structure/dos/mp-149

Thermodynamic properties

GET /materials/thermo/?formula=Fe2O3&_fields=material_id,formation_energy_per_atom,energy_above_hull

Example: Find stable oxides with band gap > 2 eV

GET /materials/summary/?elements=O&band_gap_min=2&is_stable=true&_fields=material_id,formula_pretty,band_gap,formation_energy_per_atom&_limit=10

Response Format

{
  "data": [
    {
      "material_id": "mp-149",
      "formula_pretty": "Si",
      "band_gap": 0.6105,
      "formation_energy_per_atom": 0.0
    }
  ],
  "meta": {
    "total_doc": 1
  }
}

Rate Limits

• Authenticated: ~50 requests/minute (varies by server load)
• Batch requests preferred over many individual calls
• Use _fields to reduce payload size and improve performance
• The Python client mp-api handles pagination and retries automatically

Error Format

{
  "detail": "Not authenticated"
}

HTTP 401 = missing or invalid API key. HTTP 404 = material not found. HTTP 429 = rate limited.