diff --git a/materials/surface/README.md b/materials/surface/README.md
new file mode 100644
index 0000000..7113ae2
--- /dev/null
+++ b/materials/surface/README.md
@@ -0,0 +1,81 @@
+Surface properties for various facets of a material. Contains surface energy, work function and optionally the slab models (cif) for each facet as well as data on the occupation of each facet on the Wulff shape. Surface energy is defined in units of J/m^2. Work function is defined in units of eV. 
+
+
+
+
+
+
+## Example response in JSON
+
+```json
+{"shape_factor": 4.96013873346222,
+ "surface_anisotropy": 0.04637705541263514,
+ "surfaces": [{"area_fraction": 0.19226716616368875,
+   "is_reconstructed": False,
+   "miller_index": [2, 2, 1],
+   "surface_energy": 0.5184086506489078,
+   "work_function": 2.552218081720839},
+  {"area_fraction": 0.26542926842680997,
+   "is_reconstructed": False,
+   "miller_index": [1, 0, 0],
+   "surface_energy": 0.45996547797531456,
+   "work_function": 2.714391152777596},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [1, 1, 1],
+   "surface_energy": 0.5435974664571257,
+   "work_function": 2.5988445180990416},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [2, 1, 0],
+   "surface_energy": 0.5055397635396154,
+   "work_function": 2.9873480137108213},
+  {"area_fraction": 0.15885373888143128,
+   "is_reconstructed": False,
+   "miller_index": [1, 1, 0],
+   "surface_energy": 0.4984494059571347,
+   "work_function": 3.221963437371},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [2, 1, 1],
+   "surface_energy": 0.5381822859832309,
+   "work_function": 2.9403203740003514},
+  {"area_fraction": 0.13846314062749543,
+   "is_reconstructed": False,
+   "miller_index": [3, 1, 0],
+   "surface_energy": 0.49709679154472514,
+   "work_function": 2.690052331489229},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [3, 3, 1],
+   "surface_energy": 0.5208613660199577,
+   "work_function": 2.936977763228728},
+  {"area_fraction": 0.03221908897702082,
+   "is_reconstructed": False,
+   "miller_index": [3, 1, 1],
+   "surface_energy": 0.526948562929678,
+   "work_function": 2.9073474695901087},
+  {"area_fraction": 0.05298488355024783,
+   "is_reconstructed": False,
+   "miller_index": [3, 3, 2],
+   "surface_energy": 0.5237718675797823,
+   "work_function": 2.9403203740003514},
+  {"area_fraction": 0.0031883557867715346,
+   "is_reconstructed": False,
+   "miller_index": [3, 2, 2],
+   "surface_energy": 0.5352699545482272,
+   "work_function": 2.737616060342865},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [3, 2, 1],
+   "surface_energy": 0.5343548100134592,
+   "work_function": 2.695327858441586},
+  {"area_fraction": 0.15659435758653442,
+   "is_reconstructed": False,
+   "miller_index": [3, 2, 0],
+   "surface_energy": 0.5036046642284838,
+   "work_function": 2.9450848018009306}],
+ "weighted_surface_energy": 0.495069471203702,
+ "weighted_work_function": 2.814857404756627}
+```
+
diff --git a/materials/surface/shape_factor/README.md b/materials/surface/shape_factor/README.md
new file mode 100644
index 0000000..3fdb06e
--- /dev/null
+++ b/materials/surface/shape_factor/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+4.96013873346222
+```
\ No newline at end of file
diff --git a/materials/surface/surface_anisotropy/README.md b/materials/surface/surface_anisotropy/README.md
new file mode 100644
index 0000000..886d564
--- /dev/null
+++ b/materials/surface/surface_anisotropy/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+0.04637705541263514
+```
\ No newline at end of file
diff --git a/materials/surface/surfaces/README.md b/materials/surface/surfaces/README.md
new file mode 100644
index 0000000..728b2f1
--- /dev/null
+++ b/materials/surface/surfaces/README.md
@@ -0,0 +1,70 @@
+## Example response in JSON
+
+```json
+[{"area_fraction": 0.19226716616368875,
+   "is_reconstructed": False,
+   "miller_index": [2, 2, 1],
+   "surface_energy": 0.5184086506489078,
+   "work_function": 2.552218081720839},
+  {"area_fraction": 0.26542926842680997,
+   "is_reconstructed": False,
+   "miller_index": [1, 0, 0],
+   "surface_energy": 0.45996547797531456,
+   "work_function": 2.714391152777596},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [1, 1, 1],
+   "surface_energy": 0.5435974664571257,
+   "work_function": 2.5988445180990416},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [2, 1, 0],
+   "surface_energy": 0.5055397635396154,
+   "work_function": 2.9873480137108213},
+  {"area_fraction": 0.15885373888143128,
+   "is_reconstructed": False,
+   "miller_index": [1, 1, 0],
+   "surface_energy": 0.4984494059571347,
+   "work_function": 3.221963437371},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [2, 1, 1],
+   "surface_energy": 0.5381822859832309,
+   "work_function": 2.9403203740003514},
+  {"area_fraction": 0.13846314062749543,
+   "is_reconstructed": False,
+   "miller_index": [3, 1, 0],
+   "surface_energy": 0.49709679154472514,
+   "work_function": 2.690052331489229},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [3, 3, 1],
+   "surface_energy": 0.5208613660199577,
+   "work_function": 2.936977763228728},
+  {"area_fraction": 0.03221908897702082,
+   "is_reconstructed": False,
+   "miller_index": [3, 1, 1],
+   "surface_energy": 0.526948562929678,
+   "work_function": 2.9073474695901087},
+  {"area_fraction": 0.05298488355024783,
+   "is_reconstructed": False,
+   "miller_index": [3, 3, 2],
+   "surface_energy": 0.5237718675797823,
+   "work_function": 2.9403203740003514},
+  {"area_fraction": 0.0031883557867715346,
+   "is_reconstructed": False,
+   "miller_index": [3, 2, 2],
+   "surface_energy": 0.5352699545482272,
+   "work_function": 2.737616060342865},
+  {"area_fraction": 0.0,
+   "is_reconstructed": False,
+   "miller_index": [3, 2, 1],
+   "surface_energy": 0.5343548100134592,
+   "work_function": 2.695327858441586},
+  {"area_fraction": 0.15659435758653442,
+   "is_reconstructed": False,
+   "miller_index": [3, 2, 0],
+   "surface_energy": 0.5036046642284838,
+   "work_function": 2.9450848018009306}]
+```
+
diff --git a/materials/surface/surfaces/area_fraction/README.md b/materials/surface/surfaces/area_fraction/README.md
new file mode 100644
index 0000000..4e509a5
--- /dev/null
+++ b/materials/surface/surfaces/area_fraction/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+0.19226716616368875
+```
\ No newline at end of file
diff --git a/materials/surface/surfaces/is_reconstructed/README.md b/materials/surface/surfaces/is_reconstructed/README.md
new file mode 100644
index 0000000..b609781
--- /dev/null
+++ b/materials/surface/surfaces/is_reconstructed/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+False
+```
\ No newline at end of file
diff --git a/materials/surface/surfaces/miller_index/README.md b/materials/surface/surfaces/miller_index/README.md
new file mode 100644
index 0000000..f03486b
--- /dev/null
+++ b/materials/surface/surfaces/miller_index/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+[2, 2, 1]
+```
\ No newline at end of file
diff --git a/materials/surface/surfaces/surface_energy/README.md b/materials/surface/surfaces/surface_energy/README.md
new file mode 100644
index 0000000..5396af8
--- /dev/null
+++ b/materials/surface/surfaces/surface_energy/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+0.5184086506489078
+```
\ No newline at end of file
diff --git a/materials/surface/surfaces/work_function/README.md b/materials/surface/surfaces/work_function/README.md
new file mode 100644
index 0000000..4f5a12b
--- /dev/null
+++ b/materials/surface/surfaces/work_function/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+2.552218081720839
+```
\ No newline at end of file
diff --git a/materials/surface/weighted_surface_energy/README.md b/materials/surface/weighted_surface_energy/README.md
new file mode 100644
index 0000000..0195a79
--- /dev/null
+++ b/materials/surface/weighted_surface_energy/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+0.495069471203702
+```
\ No newline at end of file
diff --git a/materials/surface/weighted_work_function/README.md b/materials/surface/weighted_work_function/README.md
new file mode 100644
index 0000000..11aff3c
--- /dev/null
+++ b/materials/surface/weighted_work_function/README.md
@@ -0,0 +1,7 @@
+
+
+## Example response in JSON
+
+```json
+2.814857404756627
+```
\ No newline at end of file