Materials Project Materials Magnetism API

openapi: 3.2.0
info:
  title: Materials Project Materials Magnetism 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 Magnetism
  description: Route providing computed magnetic ordering related data for a material following the methodology discussed by Horton *et al.* Note that magnetic data has not been calculated for all materials in the Materials Project database. See the `MagnetismDoc` schema for a full list of fields returned by this route.
paths:
  /materials/magnetism/:
    get:
      tags:
      - Materials Magnetism
      summary: Get MagnetismDoc documents
      operationId: search_materials_magnetism__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: ordering
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Ordering'
          - type: 'null'
          description: Magnetic ordering of the material.
          title: Ordering
        description: Magnetic ordering of the material.
      - name: total_magnetization_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the total magnetization.
          title: Total Magnetization Max
        description: Maximum value for the total magnetization.
      - name: total_magnetization_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the total magnetization.
          title: Total Magnetization Min
        description: Minimum value for the total magnetization.
      - name: total_magnetization_normalized_vol_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the total magnetization normalized with volume.
          title: Total Magnetization Normalized Vol Max
        description: Maximum value for the total magnetization normalized with volume.
      - name: total_magnetization_normalized_vol_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the total magnetization normalized with volume.
          title: Total Magnetization Normalized Vol Min
        description: Minimum value for the total magnetization normalized with volume.
      - name: total_magnetization_normalized_formula_units_max
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Maximum value for the total magnetization normalized with formula units.
          title: Total Magnetization Normalized Formula Units Max
        description: Maximum value for the total magnetization normalized with formula units.
      - name: total_magnetization_normalized_formula_units_min
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Minimum value for the total magnetization normalized with formula units.
          title: Total Magnetization Normalized Formula Units Min
        description: Minimum value for the total magnetization normalized with formula units.
      - name: num_magnetic_sites_max
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum value for the total number of magnetic sites.
          title: Num Magnetic Sites Max
        description: Maximum value for the total number of magnetic sites.
      - name: num_magnetic_sites_min
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Minimum value for the total number of magnetic sites.
          title: Num Magnetic Sites Min
        description: Minimum value for the total number of magnetic sites.
      - name: num_unique_magnetic_sites_max
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum value for the total number of unique magnetic sites.
          title: Num Unique Magnetic Sites Max
        description: Maximum value for the total number of unique magnetic sites.
      - name: num_unique_magnetic_sites_min
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Minimum value for the total number of unique magnetic sites.
          title: Num Unique Magnetic Sites Min
        description: Minimum value for the total number of unique magnetic sites.
      - 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 MagnetismDoc 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` `ordering` `is_magnetic` `exchange_symmetry` `num_magnetic_sites` `num_unique_magnetic_sites` `types_of_magnetic_species` `magmoms` `total_magnetization` `total_magnetization_normalized_vol` `total_magnetization_normalized_formula_units`'
          title: ' Fields'
        description: 'Fields to project from MagnetismDoc 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` `ordering` `is_magnetic` `exchange_symmetry` `num_magnetic_sites` `num_unique_magnetic_sites` `types_of_magnetic_species` `magmoms` `total_magnetization` `total_magnetization_normalized_vol` `total_magnetization_normalized_formula_units`'
      - 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 MagnetismDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_MagnetismDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Response_MagnetismDoc_:
      properties:
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/MagnetismDoc'
            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[MagnetismDoc]
    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.
    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.
    Ordering:
      type: string
      enum:
      - FM
      - AFM
      - FiM
      - NM
      - Unknown
      title: Ordering
      description: Enumeration defining possible magnetic orderings.
    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
    MagnetismDoc:
      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: magnetism
        ordering:
          anyOf:
          - type: string
          - type: 'null'
          title: Ordering
          description: Magnetic ordering.
        is_magnetic:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Magnetic
          description: Whether the material is magnetic.
        exchange_symmetry:
          anyOf:
          - type: integer
          - type: 'null'
          title: Exchange Symmetry
          description: Exchange symmetry.
        num_magnetic_sites:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Magnetic Sites
          description: The number of magnetic sites.
        num_unique_magnetic_sites:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Unique Magnetic Sites
          description: The number of unique magnetic sites.
        types_of_magnetic_species:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Types Of Magnetic Species
          description: Magnetic specie elements.
        magmoms:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Magmoms
          description: Magnetic moments for each site.
        total_magnetization:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Magnetization
          description: Total magnetization in μB.
        total_magnetization_normalized_vol:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Magnetization Normalized Vol
          description: Total magnetization normalized by volume in μB/ų.
        total_magnetization_normalized_formula_units:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Magnetization Normalized Formula Units
          description: Total magnetization normalized by formula unit in μB/f.u. .
      type: object
      title: MagnetismDoc
      description: Magnetic data obtain from the calculated structure
    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
  securitySchemes:
    ApiKeyAuth:
      descriptions: MP API key to authorize requests
      name: X-API-KEY
      in: header
      type: apiKey