Materials Project Materials Similarity API

openapi: 3.2.0
info:
  title: Materials Project Materials Similarity 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 Similarity
  description: Route providing a computed similarity metric between materials following the methodology discussed by Zimmerman *et al.* in 10.3389/fmats.2017.00034 and 10.1039/C9RA07755C. Note that similarity data has not been calculated for all materials in the Materials Project database. See the `SimilarityDoc` schema for a full list of fields returned by this route.
paths:
  /materials/similarity/:
    get:
      tags:
      - Materials Similarity
      summary: Get SimilarityDoc documents
      operationId: search_materials_similarity__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 SimilarityDoc 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` `sim` `feature_vector` `method`'
          title: ' Fields'
        description: 'Fields to project from SimilarityDoc 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` `sim` `feature_vector` `method`'
      - 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 SimilarityDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_SimilarityDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/similarity/match/:
    get:
      tags:
      - Materials Similarity
      summary: Get SimilarityDoc documents
      operationId: search_materials_similarity_match__get
      parameters:
      - name: feature_vector_hex
        in: query
        required: true
        schema:
          type: string
          maxLength: 3000
          description: A compressed, hex representation of a row unit vector of floats.
          title: Feature Vector Hex
        description: A compressed, hex representation of a row unit vector of floats.
      - name: feature_vector_norm
        in: query
        required: true
        schema:
          type: number
          description: The norm of the feature vector
          title: Feature Vector Norm
        description: The norm of the feature vector
      - name: method
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The method used to embed a structure as a feature vector.
          title: Method
        description: The method used to embed a structure as a feature vector.
      - name: _limit
        in: query
        required: false
        schema:
          type: integer
          description: Max number of entries to return in a single query. Limited to 10 by default
          default: 10
          title: ' Limit'
        description: Max number of entries to return in a single query. Limited to 10 by default
      responses:
        '200':
          description: Get SimilarityDoc data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_SimilarityDoc_'
        '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
    SimilarityEntry:
      properties:
        task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Id
          description: 'The Materials Project ID for the matched material. This comes in the form: mp-******.'
        nelements:
          anyOf:
          - type: integer
          - type: 'null'
          title: Nelements
          description: Number of elements in the matched material.
        dissimilarity:
          anyOf:
          - type: number
          - type: 'null'
          title: Dissimilarity
          description: Dissimilarity measure for the matched material in %.
        formula:
          anyOf:
          - type: string
          - type: 'null'
          title: Formula
          description: Formula of the matched material.
      type: object
      title: SimilarityEntry
      description: Find similar materials to a specified material based on crystal geometry.
    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.
    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
    Response_SimilarityDoc_:
      properties:
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/SimilarityDoc'
            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[SimilarityDoc]
    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
    SimilarityDoc:
      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
          - type: 'null'
          title: Material Id
          description: 'The Materials Project ID for the material. 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: similarity
        sim:
          anyOf:
          - items:
              $ref: '#/components/schemas/SimilarityEntry'
            type: array
          - type: 'null'
          title: Sim
          description: List containing similar structure data for a given material.
        feature_vector:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Feature Vector
          description: The feature / embedding vector of the structure.
        method:
          anyOf:
          - type: string
          - type: 'null'
          title: Method
          description: The method used to score similarity.
      type: object
      title: SimilarityDoc
      description: Model for a document containing structure similarity data
  securitySchemes:
    ApiKeyAuth:
      descriptions: MP API key to authorize requests
      name: X-API-KEY
      in: header
      type: apiKey