Materials Project Materials Chemical Environment API
The Materials Chemical Environment API from Materials Project — 1 operation(s) for materials chemical environment.
OpenAPI Specification
openapi: 3.1.0
info:
title: Materials Project Defect Tasks Materials Chemical Environment API
description: "\nThe Materials Project API allows anyone to have direct access to current, up-to-date information from the Materials Project database in a structured way.\n\nThis allows for analysis, development of automated tools, machine learning, downloading personal copies of the Materials Project database and more on a large scale.\n\nThe API is offered with the hopes of making Materials Project data more useful to you. We want you to use our data! As such, the API is offered free-of-charge and we support several tools to help you get started.\n\n## API Key\nTo make any request to the Materials Project API, you must use an API key. Your API key is generated for you automatically upon registering with the Materials Project website and is synced with the email you used to register.\n\nRemember to keep your API key safe and to not share it with anyone you do not trust.\n\nIf you are logged in, you can always access your API key from this page or from your [dashboard](https://next-gen.materialsproject.org/dashboard).\n\nIf you intend heavy API usage, you can give us a heads up by sending a message to <heavy.api.use@materialsproject.org>. With the exception of retrieving charge densities, this is not required, but may help us if we see unusual load on our servers.\n\n## Accessing Data\nTo use the API, you have three options:\n\n1. You can use our first-party supported Python client. This is the recommend route. The `mp-api` package containing the client is pip installable.\n\n ```\n pip install mp-api\n ```\n\n The `MPRester` client can be accessed by importing from it. This will ultimately replace the legacy `MPRester` available in pymatgen.\n\n For more details on how to use this, including code examples, please see <https://next-gen.materialsproject.org/api>.\n\n2. You can demo the API interactively on this documentation page. Click the \"Authorize\" button, paste in your API key, and then click the appropriate section to try out a query.\n\n3. Since this is a REST API, and offers a fully-compliant OpenAPI specification, it's possible to use the API with many libraries in many languages and environments, including JavaScript, MATLAB, Mathematica, etc. However, we do not offer first-party support for explaining how to do this, and you will have to follow the specification yourself.\n\n"
version: 0.86.4rc5.dev1+g77c2c1315
x-logo:
url: https://raw.githubusercontent.com/materialsproject/emmet/master/emmet-api/emmet/api/core/assets/mp_logo_small.png
security:
- ApiKeyAuth: []
tags:
- name: Materials Chemical Environment
paths:
/materials/chemenv/:
get:
tags:
- Materials Chemical Environment
summary: Get ChemEnvDoc documents
operationId: search_materials_chemenv__get
parameters:
- name: material_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of material_id values to query on
title: Material Ids
description: Comma-separated list of material_id values to query on
- name: chemenv_iucr
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: A comma delimited string list of unique (cationic) species in IUCR format.
title: Chemenv Iucr
description: A comma delimited string list of unique (cationic) species in IUCR format.
- name: chemenv_iupac
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: A comma delimited string list of unique (cationic) species in IUPAC format.
title: Chemenv Iupac
description: A comma delimited string list of unique (cationic) species in IUPAC format.
- name: chemenv_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: A comma delimited string list of coordination environment descriptions for unique (cationic) species.
title: Chemenv Name
description: A comma delimited string list of coordination environment descriptions for unique (cationic) species.
- name: chemenv_symbol
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: A comma delimited string list of ChemEnv symbols for unique (cationic) species in the structure.
title: Chemenv Symbol
description: A comma delimited string list of ChemEnv symbols for unique (cationic) species in the structure.
- name: species
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: A comma delimited string list of unique (cationic) species in the structure.
title: Species
description: A comma delimited string list of unique (cationic) species in the structure.
- name: csm_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Minimum value of the continous symmetry measure for any site.
title: Csm Min
description: Minimum value of the continous symmetry measure for any site.
- name: csm_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Maximum value of the continous symmetry measure for any site.
title: Csm Max
description: Maximum value of the continous symmetry measure for any site.
- name: elements
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 60
- type: 'null'
description: Query by elements in the material composition as a comma-separated list
title: Elements
description: Query by elements in the material composition as a comma-separated list
- name: exclude_elements
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 60
- type: 'null'
description: Query by excluded elements in the material composition as a comma-separated list
title: Exclude Elements
description: Query by excluded elements in the material composition as a comma-separated list
- name: nsites_max
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for maximum value of nsites
title: Nsites Max
description: Query for maximum value of nsites
- name: nsites_min
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for minimum value of nsites
title: Nsites Min
description: Query for minimum value of nsites
- name: nsites
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nsites being equal to an exact value
title: Nsites
description: Query for nsites being equal to an exact value
- name: nsites_not_eq
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nsites being not equal to an exact value
title: Nsites Not Eq
description: Query for nsites being not equal to an exact value
- name: nsites_eq_any
in: query
required: false
schema:
type: string
description: Query for nsites being any of these values. Provide a comma separated list.
title: Nsites Eq Any
description: Query for nsites being any of these values. Provide a comma separated list.
- name: nsites_neq_any
in: query
required: false
schema:
type: string
description: Query for nsites being not any of these values. Provide a comma separated list.
title: Nsites Neq Any
description: Query for nsites being not any of these values. Provide a comma separated list.
- name: nelements_max
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for maximum value of nelements
title: Nelements Max
description: Query for maximum value of nelements
- name: nelements_min
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for minimum value of nelements
title: Nelements Min
description: Query for minimum value of nelements
- name: nelements
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nelements being equal to an exact value
title: Nelements
description: Query for nelements being equal to an exact value
- name: nelements_not_eq
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for nelements being not equal to an exact value
title: Nelements Not Eq
description: Query for nelements being not equal to an exact value
- name: nelements_eq_any
in: query
required: false
schema:
type: string
description: Query for nelements being any of these values. Provide a comma separated list.
title: Nelements Eq Any
description: Query for nelements being any of these values. Provide a comma separated list.
- name: nelements_neq_any
in: query
required: false
schema:
type: string
description: Query for nelements being not any of these values. Provide a comma separated list.
title: Nelements Neq Any
description: Query for nelements being not any of these values. Provide a comma separated list.
- name: volume_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of volume
title: Volume Max
description: Query for maximum value of volume
- name: volume_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of volume
title: Volume Min
description: Query for minimum value of volume
- name: density_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of density
title: Density Max
description: Query for maximum value of density
- name: density_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of density
title: Density Min
description: Query for minimum value of density
- name: density_atomic_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of density_atomic
title: Density Atomic Max
description: Query for maximum value of density_atomic
- name: density_atomic_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of density_atomic
title: Density Atomic Min
description: Query for minimum value of density_atomic
- name: _page
in: query
required: false
schema:
type: integer
description: Page number to request (takes precedent over _limit and _skip).
title: ' Page'
description: Page number to request (takes precedent over _limit and _skip).
- name: _per_page
in: query
required: false
schema:
type: integer
description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
default: 100
title: ' Per Page'
description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
- name: _skip
in: query
required: false
schema:
type: integer
description: Number of entries to skip in the search.
default: 0
title: ' Skip'
description: Number of entries to skip in the search.
- name: _limit
in: query
required: false
schema:
type: integer
description: Max number of entries to return in a single query. Limited to 1000.
default: 100
title: ' Limit'
description: Max number of entries to return in a single query. Limited to 1000.
- name: _fields
in: query
required: false
schema:
type: string
description: 'Fields to project from ChemEnvDoc as a list of comma separated strings. Fields include: `builder_meta` `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `material_id` `deprecated` `deprecation_reasons` `last_updated` `origins` `warnings` `structure` `property_name` `valences` `species` `chemenv_symbol` `chemenv_iupac` `chemenv_iucr` `chemenv_name` `chemenv_name_with_alternatives` `csm` `method` `mol_from_site_environments` `wyckoff_positions`'
title: ' Fields'
description: 'Fields to project from ChemEnvDoc as a list of comma separated strings. Fields include: `builder_meta` `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `material_id` `deprecated` `deprecation_reasons` `last_updated` `origins` `warnings` `structure` `property_name` `valences` `species` `chemenv_symbol` `chemenv_iupac` `chemenv_iucr` `chemenv_name` `chemenv_name_with_alternatives` `csm` `method` `mol_from_site_environments` `wyckoff_positions`'
- name: _all_fields
in: query
required: false
schema:
type: boolean
description: Include all fields.
default: false
title: ' All Fields'
description: Include all fields.
responses:
'200':
description: Search for a ChemEnvDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_ChemEnvDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
TypedSiteProperitesDict:
properties:
magmom:
anyOf:
- type: number
- type: 'null'
title: Magmom
charge:
anyOf:
- type: number
- type: 'null'
title: Charge
velocities:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- type: 'null'
title: Velocities
selective_dynamics:
anyOf:
- prefixItems:
- type: boolean
- type: boolean
- type: boolean
type: array
maxItems: 3
minItems: 3
- type: 'null'
title: Selective Dynamics
coordination_no:
anyOf:
- type: integer
- type: 'null'
title: Coordination No
forces:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Forces
type: object
title: TypedSiteProperitesDict
TypedSiteDict:
properties:
label:
anyOf:
- type: string
- type: 'null'
title: Label
name:
anyOf:
- type: string
- type: 'null'
title: Name
properties:
anyOf:
- $ref: '#/components/schemas/TypedSiteProperitesDict'
- type: 'null'
species:
anyOf:
- items:
$ref: '#/components/schemas/TypedSpeciesDict'
type: array
- type: 'null'
title: Species
abc:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Abc
xyz:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Xyz
type: object
title: TypedSiteDict
TypedLatticeDict:
properties:
matrix:
items:
items:
type: number
type: array
type: array
title: Matrix
pbc:
anyOf:
- prefixItems:
- type: boolean
- type: boolean
- type: boolean
type: array
maxItems: 3
minItems: 3
- type: 'null'
title: Pbc
a:
type: number
title: A
b:
type: number
title: B
c:
type: number
title: C
alpha:
type: number
title: Alpha
beta:
type: number
title: Beta
gamma:
type: number
title: Gamma
volume:
type: number
title: Volume
type: object
required:
- matrix
- a
- b
- c
- alpha
- beta
- gamma
- volume
title: TypedLatticeDict
EmmetMeta:
properties:
emmet_version:
anyOf:
- type: string
- type: 'null'
title: Emmet Version
description: The version of emmet this document was built with.
default: 0.86.4rc4
pymatgen_version:
anyOf:
- type: string
- type: 'null'
title: Pymatgen Version
description: The version of pymatgen this document was built with.
default: 2026.4.16
run_id:
anyOf:
- type: string
- type: 'null'
title: Run Id
description: The run id associated with this data build.
batch_id:
anyOf:
- type: string
- type: 'null'
title: Batch Id
description: Identifier corresponding to the origin of this document's blessed task.
database_version:
anyOf:
- type: string
- type: 'null'
title: Database Version
description: The database version for the built data.
build_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Build Date
description: The build date for this document.
license:
anyOf:
- type: string
enum:
- BY-C
- BY-NC
- type: 'null'
title: License
description: License for the data entry.
type: object
title: EmmetMeta
description: Default emmet metadata.
ChemEnvDoc:
properties:
builder_meta:
anyOf:
- $ref: '#/components/schemas/EmmetMeta'
- type: 'null'
description: Builder metadata.
nsites:
anyOf:
- type: integer
- type: 'null'
title: Nsites
description: Total number of sites in the structure.
elements:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Elements
description: List of elements in the material.
nelements:
anyOf:
- type: integer
- type: 'null'
title: Nelements
description: Number of elements.
composition:
anyOf:
- additionalProperties:
type: number
type: object
- type: 'null'
title: Composition
description: Full composition for the material.
composition_reduced:
anyOf:
- additionalProperties:
type: number
type: object
- type: 'null'
title: Reduced Composition
description: Simplified representation of the composition.
formula_pretty:
anyOf:
- type: string
- type: 'null'
title: Pretty Formula
description: Cleaned representation of the formula.
formula_anonymous:
anyOf:
- type: string
- type: 'null'
title: Anonymous Formula
description: Anonymized representation of the formula.
chemsys:
anyOf:
- type: string
- type: 'null'
title: Chemical System
description: Dash-separated string of elements in the material.
volume:
anyOf:
- type: number
- type: 'null'
title: Volume
description: Total volume for this structure in ų.
density:
anyOf:
- type: number
- type: 'null'
title: Density
description: Density in g/cm³.
density_atomic:
anyOf:
- type: number
- type: 'null'
title: Packing Density
description: The atomic packing density in ų/atom.
symmetry:
anyOf:
- $ref: '#/components/schemas/SymmetryData'
- type: 'null'
description: Symmetry data for this material.
material_id:
anyOf:
- type: string
pattern: ^([A-Za-z]+-)?(\d+)(-[A-Za-z0-9]+)*$
examples:
- mp-3534
- '3453'
- mp-834-Ag
- type: string
examples:
- mp-ft
- task:pqrs
- type: 'null'
title: Material Id
description: 'The Materials Project ID of the material, used as a universal reference across property documents.This comes in the form: mp-******.'
deprecated:
type: boolean
title: Deprecated
description: Whether this property document is deprecated.
default: true
deprecation_reasons:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Deprecation Reasons
description: List of deprecation tags detailing why this document isn't valid.
last_updated:
type: string
format: date-time
title: Last Updated
description: Timestamp for the most recent calculation update for this property.
origins:
anyOf:
- items:
$ref: '#/components/schemas/PropertyOrigin'
type: array
- type: 'null'
title: Origins
description: Dictionary for tracking the provenance of properties.
warnings:
anyOf:
- type: string
- type: 'null'
title: Warnings
description: Warning
structure:
anyOf:
- $ref: '#/components/schemas/TypedStructureDict'
- type: 'null'
title: Structure
description: The structure used in the generation of the chemical environment data
property_name:
type: string
title: Property Name
default: coord_environment
valences:
items:
type: number
type: array
title: Valences
description: List of valences for each site in this material to determine cations
species:
items:
type: string
type: array
title: Species
description: List of unique (cationic) species in structure.
chemenv_symbol:
items:
type: string
enum:
- S:1
- L:2
- A:2
- TL:3
- TY:3
- TS:3
- T:4
- S:4
- SY:4
- SS:4
- PP:5
- S:5
- T:5
- O:6
- T:6
- PP:6
- PB:7
- ST:7
- ET:7
- FO:7
- C:8
- SA:8
- SBT:8
- TBT:8
- DD:8
- DDPN:8
- HB:8
- BO_1:8
- BO_2:8
- BO_3:8
- TC:9
- TT_1:9
- TT_2:9
- TT_3:9
- HD:9
- TI:9
- SMA:9
- SS:9
- TO_1:9
- TO_2:9
- TO_3:9
- PP:10
- PA:10
- SBSA:10
- MI:10
- BS_1:10
- BS_2:10
- TBSA:10
- PCPA:11
- H:11
- DI:11
- I:12
- PBP:12
- TT:12
- C:12
- AC:12
- SC:12
- HP:12
- HA:12
- SH:13
- DD:20
- None
type: array
title: Chemenv Symbol
description: List of ChemEnv symbols for unique (cationic) species in structure
chemenv_iupac:
items:
type: string
enum:
- TOCT-9
- CUS-10
- PPR-10
- PPRP-11
- OCF-7
- SAPRT-10
- T-4
- PAPR-10
- DD-20
- TPR-6
- OCT-8
- PP-5
- SPY-4
- HBPY-9
- A-2
- TPRT-8
- TS-3
- SS-4
- None
- SAPR-8
- SPY-5
- SAPRS-10
- HPR-12
- L-2
- PPY-6
- SP-4
- IC-12
- HBPY-8
- TPY-3
- CUS-9
- TPRS-8
- DD-8
- TBPY-5
- TP-3
- TCA-9
- PPRP-12
- SAPRS-9
- OC-6
- PBPY-7
- TPRS-7
- TPRS-9
- CU-8
- HAPR-12
- TPRT-7
type: array
title: Chemenv Iupac
description: List of symbols for unique (cationic) species in structure in IUPAC format
chemenv_iucr:
items:
type: string
enum:
- '[8do]'
- '[3n]'
- '[6p]'
- '[8cb]'
- '[5by]'
- '[12p]'
- '[6p2c]'
- '[8acb]'
- '[7by]'
- '[3l]'
- '[6p1c]'
- '[12aco]'
- '[2l]'
- None
- '[12i]'
- '[6o]'
- '[6p3c]'
- '[4n]'
- '[12co]'
- '[1l]'
- '[5y]'
- '[5l]'
- '[4l]'
- '[2n]'
- '[8by]'
- '[4t]'
- '[12tt]'
type: array
title: Chemenv Iucr
description: List of symbols for unique (cationic) species in structure in IUCR format
chemenv_name:
items:
type: string
enum:
- Pentagonal pyramid
- Metabidiminished icosahedron
- Square-face bicapped trigonal prism
- Pentagonal plane
- Cube
- Triangular cupola
- Heptagonal dipyramid
- Pentagonal prism
- T-shaped
- Square-face capped trigonal prism
- Single neighbor
- Triangular-face bicapped trigonal prism
- Pentagonal-face capped pentagonal antiprism
- Trigonal prism
- Square cupola
- See-saw
- Square non-coplanar
- Hexagonal bipyramid
- Triangular non-coplanar
- Tetrahedron
- Tricapped triangular prism (one square-face cap and two triangular-face caps)
- Square-face monocapped antiprism
- Hexagonal antiprism
- Linear
- Octahedron
- Truncated tetrahedron
- Square-face capped hexagonal prism
- Tricapped octahedron (all 3 cap faces share one atom)
- Bicapped square prism (opposite faces)
- Bicapped octahedron (cap faces with one edge in common)
- Tridiminished icosahedron
- Cuboctahedron
- Dodecahedron
- Dodecahedron with triangular faces - p2345 plane normalized
- Square-face capped square prism
- Icosahedron
- Dodecahedron with triangular faces
- Pentagonal bipyramid
- Tricapped octahedron (cap faces are aligned)
- Square pyramid
- Tricapped triangular prism (three square-face caps)
- Trigonal bipyramid
- Tricapped triangular prism (two square-face caps and one triangular-face cap)
- Pentagonal antiprism
- Diminished icosahedron
- Anticuboctahedron
- Trigonal-face bicapped square antiprism
- Bicapped octahedron (cap faces with one atom in common)
- Hexagonal prism
- Angular
- Trigonal plane
- Square plane
- Bicapped octahedron (opposed cap faces)
- Bicapped square prism (adjacent faces)
- Square antiprism
- Pentagonal-face bicapped pentagonal prism
- Square-face bicapped square antiprism
- Hendecahedron
- End-trigonal-face capped trigonal prism
- Face-capped octahedron
- Tricapped octahedron (all 3 cap faces are sharingone edge of a face)
type: array
title: Chemenv Name
description: List of text description of coordination environment for unique (cationic) species in structure.
chemenv_name_with_alternatives:
items:
type: string
enum:
- Anticuboctahedron (also known as Triangular bicupola)
- Trigonal bipyramid (also known as Trigonal dipyramid, Triangular dipyramid)
- Octahedron (also known as Square dipyramid, Square bipyramid, Triangular antiprism, Trigonal antiprism)
- Diminished icosahedron
- Square antiprism (also known as Tetragonal antiprism, Anticube)
- Square cupola
- Hexagonal bipyramid (also known as Hexagonal dipyramid)
- Square-face capped hexagonal prism
- Bicapped square prism (opposite faces) (also known as Bicapped cube)
- Square-face bicapped trigonal prism
- Square non-coplanar
- Triangular-face bicapped trigonal prism
- Square plane
- Trigonal prism (also known as Triangular prism)
- Bicapped octahedron (opposed cap faces)
- Tricapped octahedron (all 3 cap faces share one atom)
- Pentagonal prism
- Triangular cupola
- Bicapped square prism (adjacent faces) (also known as Bicapped cube)
- Cuboctahedron
- Tricapped triangular prism (two square-face caps and one triangular-face cap) (also known as Triaugment
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/materials-project/refs/heads/main/openapi/materials-project-materials-chemical-environment-api-openapi.yml