Materials Project Materials API

openapi: 3.1.0
info:
  title: Project Defect Tasks Materials 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
  description: Route for "core" information associated with a given material in the Materials Project             database. The unique identifier for a material is its `material_id` (e.g. `mp-149`). Core data in             this context refers to the crystal structure, information associated with it such as the density             and chemical formula, and the associated calculations which are identified with unique `task_id`             values. It does not contain any materials properties such as the formation energy or band gap, please             consult other property-specific endpoints for this information. See the `MaterialsDoc` schema for             a full list of fields returned by this route.
paths:
  /materials/core/blessed_tasks/:
    get:
      tags:
      - Materials
      summary: Get MaterialsDoc documents
      operationId: search_materials_core_blessed_tasks__get
      parameters:
      - name: run_type
        in: query
        required: true
        schema:
          anyOf:
          - enum:
            - GGA
            - GGA_U
            - HSE
            - PBESol
            - R2SCAN
            - SCAN
            type: string
          - type: string
          description: Calculation run type of blessed task data
          title: Run Type
        description: Calculation run type of blessed task data
      - name: energy_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum total uncorrected DFT energy in eV/atom
          title: Energy Min
        description: Minimum total uncorrected DFT energy in eV/atom
      - name: energy_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum total uncorrected DFT energy in eV/atom
          title: Energy Max
        description: Maximum total uncorrected DFT energy in eV/atom
      - 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: 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: task_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated list of task_ids to query on
          title: Task Ids
        description: Comma-separated list of task_ids to query on
      - 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: 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: license
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - BY-C
            - BY-NC
            - All
            type: string
          - type: 'null'
          description: Query by license. Can be commercial or non-commercial, or both
          default: BY-C
          title: License
        description: Query by license. Can be commercial or non-commercial, or both
      - name: _fields
        in: query
        required: false
        schema:
          type: string
          description: 'Fields to project from MaterialsDoc 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` `initial_structures` `task_ids` `deprecated_tasks` `calc_types` `created_at` `task_types` `run_types` `entries`'
          title: ' Fields'
        description: 'Fields to project from MaterialsDoc 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` `initial_structures` `task_ids` `deprecated_tasks` `calc_types` `created_at` `task_types` `run_types` `entries`'
      - 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 MaterialsDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_MaterialsDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/core/find_structure/:
    post:
      tags:
      - Materials
      summary: Post FindStructure documents
      operationId: search_materials_core_find_structure__post
      parameters:
      - name: ltol
        in: query
        required: false
        schema:
          type: number
          description: Fractional length tolerance. Default is 0.2.
          default: 0.2
          title: Ltol
        description: Fractional length tolerance. Default is 0.2.
      - name: stol
        in: query
        required: false
        schema:
          type: number
          description: Site tolerance. Defined as the fraction of the average free                     length per atom := ( V / Nsites ) ** (1/3). Default is 0.3.
          default: 0.3
          title: Stol
        description: Site tolerance. Defined as the fraction of the average free                     length per atom := ( V / Nsites ) ** (1/3). Default is 0.3.
      - name: angle_tol
        in: query
        required: false
        schema:
          type: number
          description: Angle tolerance in degrees. Default is 5 degrees.
          default: 5
          title: Angle Tol
        description: Angle tolerance in degrees. Default is 5 degrees.
      - name: _limit
        in: query
        required: false
        schema:
          type: integer
          description: Maximum number of matches to show. Defaults to 1, only showing the best match.
          default: 1
          title: ' Limit'
        description: Maximum number of matches to show. Defaults to 1, only showing the best match.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: Dictionary representaion of Pymatgen structure object to query with
              title: Structure
      responses:
        '200':
          description: Post FindStructure data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_FindStructure_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/core/formula_autocomplete/:
    get:
      tags:
      - Materials
      summary: Get FormulaAutocomplete documents
      operationId: search_materials_core_formula_autocomplete__get
      parameters:
      - name: formula
        in: query
        required: true
        schema:
          type: string
          description: Human readable chemical formula.
          title: Formula
        description: Human readable chemical formula.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: Maximum number of matches to show. Defaults to 10.
          default: 10
          title: Limit
        description: Maximum number of matches to show. Defaults to 10.
      responses:
        '200':
          description: Get FormulaAutocomplete data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_FormulaAutocomplete_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/core/:
    get:
      tags:
      - Materials
      summary: Get MaterialsDoc documents
      operationId: search_materials_core__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: 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: task_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated list of task_ids to query on
          title: Task Ids
        description: Comma-separated list of task_ids to query on
      - name: crystal_system
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Crystal system of the material. If a comma-separated string, will query by multiple crystal systems.
          title: Crystal System
        description: Crystal system of the material. If a comma-separated string, will query by multiple crystal systems.
      - name: spacegroup_number
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: string
          - type: 'null'
          description: Space group number of the material. If a comma-separated string, will query by multiple space group numbers.
          title: Spacegroup Number
        description: Space group number of the material. If a comma-separated string, will query by multiple space group numbers.
      - name: spacegroup_symbol
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Space group symbol of the material. If a comma-separated string, will query by multiple space group numbers.
          title: Spacegroup Symbol
        description: Space group symbol of the material. If a comma-separated string, will query by multiple space group numbers.
      - 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: 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 MaterialsDoc 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` `initial_structures` `task_ids` `deprecated_tasks` `calc_types` `created_at` `task_types` `run_types` `entries`'
          title: ' Fields'
        description: 'Fields to project from MaterialsDoc 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` `initial_structu

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