Materials Project Materials Electronic Structure API

openapi: 3.1.0
info:
  title: Materials Project Defect Tasks Materials Electronic Structure 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 Electronic Structure
  description: Routes providing computed electronic structure related data for a material such as             band gap and fermi level. Python objects for line-mode band structures, density of states, and             fermi surfaces are also available. This data was obtained following the methodology discussed by             [Munro *et al.*](https://doi.org/10.1038/s41524-020-00383-7) and [Ganose *et al.*](https://doi.org/10.21105/joss.03089)             Note that full band structure, density of states, and fermi surface data has not been calculated for             all materials in the Materials Project database. See the `ElectronicStructureDoc` and `FermiDoc` schema             for a full list of fields returned by the associated routes.
  externalDocs:
    description: For a more detailed description
    url: https://docs.materialsproject.org/methodology/electronic-structure
paths:
  /materials/fermi/:
    get:
      tags:
      - Materials Electronic Structure
      summary: Get FermiDoc documents
      operationId: search_materials_fermi__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: _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 FermiDoc as a list of comma separated strings.                    Fields include: `fermi_surfaces` `surface_types` `material_id` `last_updated`'
          title: ' Fields'
        description: 'Fields to project from FermiDoc as a list of comma separated strings.                    Fields include: `fermi_surfaces` `surface_types` `material_id` `last_updated`'
      - 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 FermiDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_FermiDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/electronic_structure/bandstructure/:
    get:
      tags:
      - Materials Electronic Structure
      summary: Get ElectronicStructureDoc documents
      operationId: search_materials_electronic_structure_bandstructure__get
      parameters:
      - name: path_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: k-path selection convention for the band structure.
          title: Path Type
        description: k-path selection convention for the band structure.
      - name: band_gap_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the band gap energy in eV.
          title: Band Gap Max
        description: Maximum value for the band gap energy in eV.
      - name: band_gap_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the band gap energy in eV.
          title: Band Gap Min
        description: Minimum value for the band gap energy in eV.
      - name: efermi_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the fermi energy in eV.
          title: Efermi Max
        description: Maximum value for the fermi energy in eV.
      - name: efermi_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the fermi energy in eV.
          title: Efermi Min
        description: Minimum value for the fermi energy in eV.
      - name: magnetic_ordering
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Ordering'
          - type: 'null'
          description: Magnetic ordering associated with the data.
          title: Magnetic Ordering
        description: Magnetic ordering associated with the data.
      - name: is_gap_direct
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether a band gap is direct or not.
          title: Is Gap Direct
        description: Whether a band gap is direct or not.
      - name: is_metal
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the material is considered a metal.
          title: Is Metal
        description: Whether the material is considered a metal.
      - name: deprecated
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the material is marked as deprecated
          default: false
          title: Deprecated
        description: Whether the material is marked as deprecated
      - 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 ElectronicStructureDoc as a list of comma separated strings.                    Fields include: `task_id` `band_gap` `cbm` `vbm` `efermi` `is_gap_direct` `is_metal` `magnetic_ordering` `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` `bandstructure` `dos`'
          title: ' Fields'
        description: 'Fields to project from ElectronicStructureDoc as a list of comma separated strings.                    Fields include: `task_id` `band_gap` `cbm` `vbm` `efermi` `is_gap_direct` `is_metal` `magnetic_ordering` `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` `bandstructure` `dos`'
      - 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 ElectronicStructureDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_ElectronicStructureDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/electronic_structure/dos/:
    get:
      tags:
      - Materials Electronic Structure
      summary: Get ElectronicStructureDoc documents
      operationId: search_materials_electronic_structure_dos__get
      parameters:
      - name: projection_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Projection type for the density of states data.
          title: Projection Type
        description: Projection type for the density of states data.
      - name: spin
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - '1'
            - '-1'
            type: string
          - $ref: '#/components/schemas/Spin'
          - type: 'null'
          description: Spin channel for density of states data. '1' corresponds to spin up.
          title: Spin
        description: Spin channel for density of states data. '1' corresponds to spin up.
      - name: element
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Element'
          - type: 'null'
          description: Element type for projected density of states data.
          title: Element
        description: Element type for projected density of states data.
      - name: orbital
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/OrbitalType'
          - type: 'null'
          description: Orbital type for projected density of states data.
          title: Orbital
        description: Orbital type for projected density of states data.
      - name: band_gap_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the band gap energy in eV.
          title: Band Gap Max
        description: Maximum value for the band gap energy in eV.
      - name: band_gap_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the band gap energy in eV.
          title: Band Gap Min
        description: Minimum value for the band gap energy in eV.
      - name: efermi_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the fermi energy in eV.
          title: Efermi Max
        description: Maximum value for the fermi energy in eV.
      - name: efermi_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the fermi energy in eV.
          title: Efermi Min
        description: Minimum value for the fermi energy in eV.
      - name: magnetic_ordering
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Ordering'
          - type: 'null'
          description: Magnetic ordering associated with the data.
          title: Magnetic Ordering
        description: Magnetic ordering associated with the data.
      - name: deprecated
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the material is marked as deprecated
          default: false
          title: Deprecated
        description: Whether the material is marked as deprecated
      - 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 ElectronicStructureDoc as a list of comma separated strings.                    Fields include: `task_id` `band_gap` `cbm` `vbm` `efermi` `is_gap_direct` `is_metal` `magnetic_ordering` `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` `bandstructure` `dos`'
          title: ' Fields'
        description: 'Fields to project from ElectronicStructureDoc as a list of comma separated strings.                    Fields include: `task_id` `band_gap` `cbm` `vbm` `efermi` `is_gap_direct` `is_metal` `magnetic_ordering` `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` `bandstructure` `dos`'
      - 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 ElectronicStructureDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_ElectronicStructureDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/electronic_structure/:
    get:
      tags:
      - Materials Electronic Structure
      summary: Get ElectronicStructureDoc documents
      operationId: search_materials_electronic_structure__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: magnetic_ordering
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Ordering'
          - type: 'null'
          description: Magnetic ordering associated with the data.
          title: Magnetic Ordering
        description: Magnetic ordering associated with the data.
      - name: is_gap_direct
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether a band gap is direct or not.
          title: Is Gap Direct
        description: Whether a band gap is direct or not.
      - name: is_metal
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the material is considered a metal.
          title: Is Metal
        description: Whether the material is considered a metal.
      - name: formula
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query by formula including anonymized formula or by including wild cards. A comma delimited string list of anonymous formulas or regular formulas can also be provided.
          title: Formula
        description: Query by formula including anonymized formula or by including wild cards. A comma delimited string list of anonymous formulas or regular formulas can also be provided.
      - name: chemsys
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: A comma delimited string list of chemical systems. Wildcards for unknown elements only supported for single chemsys queries
          title: Chemsys
        description: A comma delimited string list of chemical systems. Wildcards for unknown elements only supported for single chemsys queries
      - 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: band_gap_max
        in: query
        required: false
        schema:
          type: number
          description: Query for maximum value of band_gap
          title: Band Gap Max
        description: Query for maximum value of band_gap
      - name: band_gap_min
        in: query
        required: false
        schema:
          type: number
          description: Query for minimum value of band_gap
          title: Band Gap Min
        description: Query for minimum value of band_gap
      - name: cbm_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Query for maximum value of cbm
          title: Cbm Max
        description: Query for maximum value of cbm
      - name: cbm_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Query for minimum value of cbm
          title: Cbm Min
        description: Query for minimum value of cbm
      - name: vbm_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Query for maximum value of vbm
          title: Vbm Max
        description: Query for maximum value of vbm
      - name: vbm_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Query for minimum value of vbm
          title: Vbm Min
        description: Query for minimum value of vbm
      - name: efermi_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Query for maximum value of efermi
          title: Efermi Max
        description: Query for maximum value of efermi
      - name: efermi_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Query for minimum value of efermi
          title: Efermi Min
        description: Query for minimum value of efermi
      - 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: deprecated
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the material is marked as deprecated
          default: false
          title: Deprecated
        description: Whether the material is marked as deprecated
      - 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:

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/materials-project/refs/heads/main/openapi/materials-project-materials-electronic-structure-api-openapi.yml