Route providing computed surface property data for a material following the methodology discussed by [Tran *et al.*](https://doi.org/10.1038/sdata.2016.80) Note that surface data has not been calculated for all materials in the Materials Project database. See the `SurfacePropDoc` schema for a full list of fields returned by this route.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/materials-project-materials-surface-properties-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Materials Project Materials Surface Properties 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 Surface Properties
description: Route providing computed surface property data for a material following the methodology discussed by Tran *et al.* Note that surface data has not been calculated for all materials in the Materials Project database. See the `SurfacePropDoc` schema for a full list of fields returned by this route.
paths:
/materials/surface_properties/:
get:
tags:
- Materials Surface Properties
summary: Get SurfacePropDoc documents
operationId: search_materials_surface_properties__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: weighted_surface_energy_EV_PER_ANG2_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of weighted_surface_energy_EV_PER_ANG2
title: Weighted Surface Energy Ev Per Ang2 Max
description: Query for maximum value of weighted_surface_energy_EV_PER_ANG2
- name: weighted_surface_energy_EV_PER_ANG2_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of weighted_surface_energy_EV_PER_ANG2
title: Weighted Surface Energy Ev Per Ang2 Min
description: Query for minimum value of weighted_surface_energy_EV_PER_ANG2
- name: weighted_surface_energy_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of weighted_surface_energy
title: Weighted Surface Energy Max
description: Query for maximum value of weighted_surface_energy
- name: weighted_surface_energy_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of weighted_surface_energy
title: Weighted Surface Energy Min
description: Query for minimum value of weighted_surface_energy
- name: surface_anisotropy_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of surface_anisotropy
title: Surface Anisotropy Max
description: Query for maximum value of surface_anisotropy
- name: surface_anisotropy_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of surface_anisotropy
title: Surface Anisotropy Min
description: Query for minimum value of surface_anisotropy
- name: shape_factor_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of shape_factor
title: Shape Factor Max
description: Query for maximum value of shape_factor
- name: shape_factor_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of shape_factor
title: Shape Factor Min
description: Query for minimum value of shape_factor
- name: weighted_work_function_max
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for maximum value of weighted_work_function
title: Weighted Work Function Max
description: Query for maximum value of weighted_work_function
- name: weighted_work_function_min
in: query
required: false
schema:
anyOf:
- type: number
- type: 'null'
description: Query for minimum value of weighted_work_function
title: Weighted Work Function Min
description: Query for minimum value of weighted_work_function
- name: has_reconstructed
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Whether the entry has a reconstructed surface.
title: Has Reconstructed
description: Whether the entry has a reconstructed surface.
- 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 SurfacePropDoc as a list of comma separated strings. Fields include: `surfaces` `weighted_surface_energy_EV_PER_ANG2` `weighted_surface_energy` `surface_anisotropy` `pretty_formula` `shape_factor` `weighted_work_function` `has_reconstructed` `material_id` `structure`'
title: ' Fields'
description: 'Fields to project from SurfacePropDoc as a list of comma separated strings. Fields include: `surfaces` `weighted_surface_energy_EV_PER_ANG2` `weighted_surface_energy` `surface_anisotropy` `pretty_formula` `shape_factor` `weighted_work_function` `has_reconstructed` `material_id` `structure`'
- 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 SurfacePropDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_SurfacePropDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
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
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
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
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
SurfaceEntry:
properties:
miller_index:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Miller Index
description: Miller index of surface.
surface_energy_EV_PER_ANG2:
anyOf:
- type: number
- type: 'null'
title: Surface Energy Ev Per Ang2
description: Surface energy in eV/Ų.
surface_energy:
anyOf:
- type: number
- type: 'null'
title: Surface Energy
description: Surface energy in J/m².
is_reconstructed:
anyOf:
- type: boolean
- type: 'null'
title: Is Reconstructed
description: Whether it is a reconstructed surface.
structure:
anyOf:
- $ref: '#/components/schemas/TypedStructureDict'
- type: 'null'
title: Structure
description: Slab structure.
work_function:
anyOf:
- type: number
- type: 'null'
title: Work Function
description: Work function in eV.
efermi:
anyOf:
- type: number
- type: 'null'
title: Efermi
description: Fermi energy in eV.
area_fraction:
anyOf:
- type: number
- type: 'null'
title: Area Fraction
description: Area fraction.
has_wulff:
anyOf:
- type: boolean
- type: 'null'
title: Has Wulff
description: Whether the surface has wulff entry.
type: object
title: SurfaceEntry
description: Surface energies, miller indicies, ...
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
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.
Response_SurfacePropDoc_:
properties:
data:
anyOf:
- items:
$ref: '#/components/schemas/SurfacePropDoc'
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[SurfacePropDoc]
SurfacePropDoc:
properties:
surfaces:
anyOf:
- items:
$ref: '#/components/schemas/SurfaceEntry'
type: array
- type: 'null'
title: Surfaces
description: List of individual surface data.
weighted_surface_energy_EV_PER_ANG2:
anyOf:
- type: number
- type: 'null'
title: Weighted Surface Energy Ev Per Ang2
description: Weighted surface energy in eV/Ų
weighted_surface_energy:
anyOf:
- type: number
- type: 'null'
title: Weighted Surface Energy
description: Weighted surface energy in J/m²
surface_anisotropy:
anyOf:
- type: number
- type: 'null'
title: Surface Anisotropy
description: Surface energy anisotropy.
pretty_formula:
anyOf:
- type: string
- type: 'null'
title: Pretty Formula
description: Reduced Formula of the material.
shape_factor:
anyOf:
- type: number
- type: 'null'
title: Shape Factor
description: Shape factor.
weighted_work_function:
anyOf:
- type: number
- type: 'null'
title: Weighted Work Function
description: Weighted work function in eV.
has_reconstructed:
anyOf:
- type: boolean
- type: 'null'
title: Has Reconstructed
description: Whether the entry has any reconstructed surfaces.
material_id:
anyOf:
- type: string
- type: 'null'
title: Material Id
description: 'The Materials Project ID of the material. This comes in the form: mp-******.'
structure:
anyOf:
- $ref: '#/components/schemas/TypedStructureDict'
- type: 'null'
title: Structure
description: The conventional crystal structure of the material.
type: object
title: SurfacePropDoc
description: Model for a document containing surface properties data
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
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
securitySchemes:
ApiKeyAuth:
descriptions: MP API key to authorize requests
name: X-API-KEY
in: header
type: apiKey