**Under construction** Route providing computed phonon data for a material following the methodology discussed by [Petretto *et al.*](https://doi.org/10.1038/sdata.2018.65) Note that phonon data has not been calculated for all materials in the Materials Project database. See the `PhononBSDOSDoc` schema for a full list of fields returned by this route.
openapi: 3.1.0
info:
title: Materials Project Defect Tasks Materials Phonon 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 Phonon
description: '**Under construction** Route providing computed phonon data for a material following the methodology discussed by [Petretto *et al.*](https://doi.org/10.1038/sdata.2018.65) Note that phonon data has not been calculated for all materials in the Materials Project database. See the `PhononBSDOSDoc` schema for a full list of fields returned by this route.'
externalDocs:
description: For a more detailed description
url: https://docs.materialsproject.org/methodology/phonons
paths:
/materials/phonon/:
get:
tags:
- Materials Phonon
summary: Get PhononBSDOSDoc documents
operationId: search_materials_phonon__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: 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: phonon_method
in: query
required: false
schema:
type: string
description: Phonon Method to search for
title: Phonon Method
description: Phonon Method to search for
- 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: total_dft_energy_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of total_dft_energy
title: Total Dft Energy Max
description: Query for maximum value of total_dft_energy
- name: total_dft_energy_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of total_dft_energy
title: Total Dft Energy Min
description: Query for minimum value of total_dft_energy
- name: volume_per_formula_unit_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of volume_per_formula_unit
title: Volume Per Formula Unit Max
description: Query for maximum value of volume_per_formula_unit
- name: volume_per_formula_unit_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of volume_per_formula_unit
title: Volume Per Formula Unit Min
description: Query for minimum value of volume_per_formula_unit
- name: formula_units_max
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for maximum value of formula_units
title: Formula Units Max
description: Query for maximum value of formula_units
- name: formula_units_min
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for minimum value of formula_units
title: Formula Units Min
description: Query for minimum value of formula_units
- name: formula_units
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for formula_units being equal to an exact value
title: Formula Units
description: Query for formula_units being equal to an exact value
- name: formula_units_not_eq
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Query for formula_units being not equal to an exact value
title: Formula Units Not Eq
description: Query for formula_units being not equal to an exact value
- name: formula_units_eq_any
in: query
required: false
schema:
type: string
description: Query for formula_units being any of these values. Provide a comma separated list.
title: Formula Units Eq Any
description: Query for formula_units being any of these values. Provide a comma separated list.
- name: formula_units_neq_any
in: query
required: false
schema:
type: string
description: Query for formula_units being not any of these values. Provide a comma separated list.
title: Formula Units Neq Any
description: Query for formula_units being not any of these values. Provide a comma separated list.
- 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 PhononBSDOSDoc as a list of comma separated strings. Fields include: `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `identifier` `phonon_method` `phonon_bandstructure` `phonon_dos` `epsilon_static` `epsilon_electronic` `born` `force_constants` `last_updated` `sum_rules_breaking` `structure` `total_dft_energy` `volume_per_formula_unit` `formula_units` `supercell_matrix` `primitive_matrix` `code` `post_process_settings` `thermal_displacement_data` `calc_meta` `material_id` `task_ids`'
title: ' Fields'
description: 'Fields to project from PhononBSDOSDoc as a list of comma separated strings. Fields include: `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `identifier` `phonon_method` `phonon_bandstructure` `phonon_dos` `epsilon_static` `epsilon_electronic` `born` `force_constants` `last_updated` `sum_rules_breaking` `structure` `total_dft_energy` `volume_per_formula_unit` `formula_units` `supercell_matrix` `primitive_matrix` `code` `post_process_settings` `thermal_displacement_data` `calc_meta` `material_id` `task_ids`'
- 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 PhononBSDOSDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_PhononBSDOSDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
PhononComputationalSettings:
properties:
npoints_band:
anyOf:
- type: integer
- type: 'null'
title: Npoints Band
description: number of points for band structure computation
kpath_scheme:
anyOf:
- type: string
- type: 'null'
title: Kpath Scheme
description: indicates the kpath scheme
kpoint_density_dos:
anyOf:
- type: integer
- type: 'null'
title: Kpoint Density Dos
description: number of points for computation of free energies and densities of states
type: object
title: PhononComputationalSettings
description: Collection to store computational settings for the phonon computation.
Response_PhononBSDOSDoc_:
properties:
data:
anyOf:
- items:
$ref: '#/components/schemas/PhononBSDOSDoc'
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[PhononBSDOSDoc]
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
PhononBS:
properties:
identifier:
anyOf:
- type: string
- type: 'null'
title: Identifier
description: The identifier of this object.
structure:
anyOf:
- $ref: '#/components/schemas/TypedStructureDict'
- type: 'null'
title: Structure
description: The structure associated with this calculation.
path_convention:
type: string
title: Path Convention
description: High symmetry path convention of the band structure
default: unknown
kpath:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Kpath
labels_dict:
additionalProperties:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: object
title: Labels Dict
description: The high-symmetry labels of specific q-points.
default: {}
qpoints:
items:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
title: Qpoints
description: The wave vectors (q-points) at which the band structure was sampled, in direct coordinates.
reciprocal_lattice:
prefixItems:
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
maxItems: 3
minItems: 3
title: Reciprocal Lattice
description: The reciprocal lattice.
has_nac:
type: boolean
title: Has Nac
description: Whether the calculation includes non-analytical corrections at Gamma.
default: false
frequencies:
items:
items:
type: number
type: array
type: array
title: Frequencies
description: The eigen-frequencies, with the first index representing the band, and the second the k-point.
eigendisplacements:
additionalProperties:
items:
items:
items:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
type: array
type: array
type: object
title: Eigendisplacements
description: Phonon eigendisplacements in Cartesian coordinates.
default:
imag: 0
type: object
required:
- qpoints
- reciprocal_lattice
- frequencies
title: PhononBS
description: Define schema of pymatgen phonon band structure.
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.
ThermalDisplacementData:
properties:
freq_min_thermal_displacements:
anyOf:
- type: number
- type: 'null'
title: Freq Min Thermal Displacements
description: cutoff frequency in THz to avoid numerical issues in the computation of the thermal displacement parameters
thermal_displacement_matrix_cif:
anyOf:
- items:
items:
prefixItems:
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
maxItems: 3
minItems: 3
type: array
type: array
- type: 'null'
title: Thermal Displacement Matrix Cif
description: field including thermal displacement matrices in CIF format
thermal_displacement_matrix:
anyOf:
- items:
items:
prefixItems:
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
maxItems: 3
minItems: 3
type: array
type: array
- type: 'null'
title: Thermal Displacement Matrix
description: field including thermal displacement matrices in Cartesian coordinate system
temperatures_thermal_displacements:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Temperatures Thermal Displacements
description: temperatures at which the thermal displacement matriceshave been computed
type: object
title: ThermalDisplacementData
description: Collection to store information on the thermal displacement matrices.
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
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
PhononBSDOSDoc:
properties:
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'
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/materials-project/refs/heads/main/openapi/materials-project-materials-phonon-api-openapi.yml