Materials Project Materials Bonds API

openapi: 3.2.0
info:
  title: Materials Project Materials Bonds API
  description: The Materials Project API allows anyone to have direct access to current, up-to-date information from the Materials Project database in a structured way.
  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 Bonds
  description: Route for retrevial of bonding information for a given material.
paths:
  /materials/bonds/:
    get:
      tags:
      - Materials Bonds
      summary: Get BondingDoc documents
      operationId: search_materials_bonds__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: max_bond_length_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the maximum bond length in the structure.
          title: Max Bond Length Max
        description: Maximum value for the maximum bond length in the structure.
      - name: max_bond_length_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the maximum bond length in the structure.
          title: Max Bond Length Min
        description: Minimum value for the maximum bond length in the structure.
      - name: min_bond_length_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the minimum bond length in the structure.
          title: Min Bond Length Max
        description: Maximum value for the minimum bond length in the structure.
      - name: min_bond_length_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the minimum bond length in the structure.
          title: Min Bond Length Min
        description: Minimum value for the minimum bond length in the structure.
      - name: mean_bond_length_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the mean bond length in the structure.
          title: Mean Bond Length Max
        description: Maximum value for the mean bond length in the structure.
      - name: mean_bond_length_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the mean bond length in the structure.
          title: Mean Bond Length Min
        description: Minimum value for the mean bond length in the structure.
      - name: coordination_envs
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query by coordination environments in the material composition as a comma-separated list (e.g. 'Mo-S(6),S-Mo(3)')
          title: Coordination Envs
        description: Query by coordination environments in the material composition as a comma-separated list (e.g. 'Mo-S(6),S-Mo(3)')
      - name: coordination_envs_anonymous
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query by anonymous coordination environments in the material composition as a comma-separated list (e.g. 'A-B(6),A-B(3)')
          title: Coordination Envs Anonymous
        description: Query by anonymous coordination environments in the material composition as a comma-separated list (e.g. 'A-B(6),A-B(3)')
      - 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 BondingDoc 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` `structure_graph` `method` `bond_types` `bond_length_stats` `coordination_envs` `coordination_envs_anonymous`'
          title: ' Fields'
        description: 'Fields to project from BondingDoc 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` `structure_graph` `method` `bond_types` `bond_length_stats` `coordination_envs` `coordination_envs_anonymous`'
      - 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 BondingDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_BondingDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    TypedSpeciesDict:
      properties:
        element:
          anyOf:
          - type: string
          - type: 'null'
          title: Element
        oxidation_state:
          anyOf:
          - type: number
          - type: 'null'
          title: Oxidation State
        spin:
          anyOf:
          - type: number
          - type: 'null'
          title: Spin
        occu:
          anyOf:
          - type: number
          - type: 'null'
          title: Occu
      type: object
      title: TypedSpeciesDict
    Response_BondingDoc_:
      properties:
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/BondingDoc'
            type: array
          - type: 'null'
          title: Data
          description: List of returned data
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/Error'
            type: array
          - type: 'null'
          title: Errors
          description: Any errors on processing this query
        meta:
          anyOf:
          - $ref: '#/components/schemas/Meta'
          - type: 'null'
          description: Extra information for the query
      type: object
      title: Response[BondingDoc]
    TypedStructureGraphDict:
      properties:
        '@module':
          type: string
          title: '@Module'
        '@class':
          type: string
          title: '@Class'
        structure:
          $ref: '#/components/schemas/TypedStructureDict'
        graphs:
          $ref: '#/components/schemas/TypedGraphDict'
      type: object
      required:
      - '@module'
      - '@class'
      - structure
      - graphs
      title: TypedStructureGraphDict
    SymmetryData:
      properties:
        crystal_system:
          anyOf:
          - type: string
          - type: 'null'
          title: Crystal System
          description: The crystal system for this lattice.
        symbol:
          anyOf:
          - type: string
          - type: 'null'
          title: Space Group Symbol
          description: The spacegroup symbol for the lattice.
        hall:
          anyOf:
          - type: string
          - type: 'null'
          title: Hall Symbol
          description: Hall symbol for the lattice
        number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Space Group Number
          description: The spacegroup number for the lattice.
        point_group:
          anyOf:
          - type: string
          - type: 'null'
          title: Point Group Symbol
          description: The point group for the lattice.
        symprec:
          anyOf:
          - type: number
          - type: 'null'
          title: Symmetry Finding Precision
          description: The precision provided to spglib to determine the symmetry of this structure.
        angle_tolerance:
          anyOf:
          - type: number
          - type: 'null'
          title: Angle Tolerance
          description: Angle tolerance provided to spglib to determine the symmetry of this structure.
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: spglib version
      type: object
      title: SymmetryData
      description: Defines a symmetry data set for materials documents
    TypedAggregateProperitesDict:
      properties:
        magmom:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Magmom
        charge:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Charge
        velocities:
          anyOf:
          - items:
              prefixItems:
              - type: number
              - type: number
              - type: number
              type: array
              maxItems: 3
              minItems: 3
            type: array
          - type: 'null'
          title: Velocities
        selective_dynamics:
          anyOf:
          - items:
              prefixItems:
              - type: boolean
              - type: boolean
              - type: boolean
              type: array
              maxItems: 3
              minItems: 3
            type: array
          - type: 'null'
          title: Selective Dynamics
      type: object
      title: TypedAggregateProperitesDict
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GraphDescriptorDict:
      properties:
        name:
          type: string
          title: Name
        edge_weight_name:
          type: string
          title: Edge Weight Name
        edge_weight_units:
          type: string
          title: Edge Weight Units
      type: object
      required:
      - name
      title: GraphDescriptorDict
    TypedStructureDict:
      properties:
        '@module':
          type: string
          title: '@Module'
        '@class':
          type: string
          title: '@Class'
        charge:
          anyOf:
          - type: number
          - type: 'null'
          title: Charge
        lattice:
          $ref: '#/components/schemas/TypedLatticeDict'
        sites:
          items:
            $ref: '#/components/schemas/TypedSiteDict'
          type: array
          title: Sites
        properties:
          anyOf:
          - $ref: '#/components/schemas/TypedAggregateProperitesDict'
          - type: 'null'
      type: object
      required:
      - '@module'
      - '@class'
      - lattice
      - sites
      title: TypedStructureDict
    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.
    BondingDoc:
      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:
          items:
            type: string
          type: array
          title: Warnings
          description: Any warnings related to this property.
          default: []
        property_name:
          type: string
          title: Property Name
          default: bonding
        structure_graph:
          $ref: '#/components/schemas/TypedStructureGraphDict'
          title: Structure Graph
          description: Structure graph
        method:
          type: string
          title: Method
          description: Method used to compute structure graph.
        bond_types:
          additionalProperties:
            items:
              type: number
            type: array
          type: object
          title: Bond Types
          description: Dictionary of bond types to their length, e.g. a Fe-O to a list of the lengths of Fe-O bonds in Angstrom.
        bond_length_stats:
          $ref: '#/components/schemas/TypedBondLengthStatsDict'
          description: 'Dictionary of statistics of bonds in structure '
        coordination_envs:
          items:
            type: string
          type: array
          title: Coordination Envs
          description: List of co-ordination environments, e.g. ['Mo-S(6)', 'S-Mo(3)'].
        coordination_envs_anonymous:
          items:
            type: string
          type: array
          title: Coordination Envs Anonymous
          description: List of co-ordination environments without elements present, e.g. ['A-B(6)', 'A-B(3)'].
      type: object
      required:
      - structure_graph
      - method
      - bond_types
      - bond_length_stats
      - coordination_envs
      - coordination_envs_anonymous
      title: BondingDoc
      description: 'Structure graphs representing chemical bonds calculated from structure

        using near neighbor strategies as defined in pymatgen.'
    Meta:
      properties:
        api_version:
          type: string
          title: Api Version
          description: A string containing the version of the Materials API implementation, e.g. v0.9.5
          default: 0.86.4rc5.dev1+g77c2c1315
        time_stamp:
          type: string
          format: date-time
          title: Time Stamp
          description: A string containing the date and time at which the query was executed
        total_doc:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Total Doc
          description: The total number of documents available for this query
        facet:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Facet
          description: A dictionary containing the facets available for this query
      additionalProperties: true
      type: object
      title: Meta
      description: Meta information for the MAPI Response.
    TypedBondLengthStatsDict:
      properties:
        all_weights:
          items:
            type: number
          type: array
          title: All Weights
        min:
          type: number
          title: Min
        max:
          type: number
          title: Max
        mean:
          type: number
          title: Mean
        variance:
          type: number
          title: Variance
      type: object
      required:
      - all_weights
      - min
      - max
      - mean
      - variance
      title: TypedBondLengthStatsDict
    PropertyOrigin:
      properties:
        name:
          type: string
          title: Name
          description: The property name
        task_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
          title: Task Id
          description: The calculation ID this property comes from.
        last_updated:
          type: string
          format: date-time
          title: Last Updated
          description: The timestamp when this calculation was last updated
      type: object
      required:
      - name
      - task_id
      title: PropertyOrigin
      description: Provenance document for the origin of properties in a material document
    TypedAdjacencyDict:
      properties:
        to_jimage:
          prefixItems:
          - type: integer
          - type: integer
          - type: integer
          type: array
          maxItems: 3
          minItems: 3
          title: To Jimage
        weight:
          type: number
          title: Weight
        id:
          type: integer
          title: Id
        key:
          type: integer
          title: Key
      type: object
      required:
      - to_jimage
      - weight
      - id
      - key
      title: TypedAdjacencyDict
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TypedNodeDict:
      properties:
        id:
          type: integer
          title: Id
      type: object
      required:
      - id
      title: TypedNodeDict
    Error:
      properties:
        code:
          type: integer
          title: Code
          description: The error code
        message:
          type: string
          title: Message
          description: The description of the error
      type: object
      required:
      - code
      - message
      title: Error
      description: Base Error model for General API.
    TypedGraphDict:
      properties:
        directed:
          type: boolean
          title: Directed
        multigraph:
          type: boolean
          title: Multigraph
        graph:
          $ref: '#/components/schemas/GraphDescriptorDict'
        nodes:
          items:
            $ref: '#/components/schemas/TypedNodeDict'
          type: array
          title: Nodes
        adjacency:
          items:
            items:
              $ref: '#/components/schemas/TypedAdjacencyDict'
            type: array
          type: array
          title: Adjacency
      type: object
      required:
      - directed
      - multigraph
      - graph
      - nodes
      - adjacency
      title: TypedGraphDict
  securitySchemes:
    ApiKeyAuth:
      descriptions: MP API key to authorize requests
      name: X-API-KEY
      in: header
      type: apiKey