From 0fb93b1e8a457eede96da97174a7e99b4d698fa2 Mon Sep 17 00:00:00 2001
From: marc tobias <mtmail@gmx.net>
Date: Mon, 4 May 2020 17:06:06 +0200
Subject: [PATCH] documenation for /status endpoint

---
 docs/api/Status.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/mkdocs.yml    |  1 +
 2 files changed, 61 insertions(+)
 create mode 100644 docs/api/Status.md

diff --git a/docs/api/Status.md b/docs/api/Status.md
new file mode 100644
index 00000000..0241b6fa
--- /dev/null
+++ b/docs/api/Status.md
@@ -0,0 +1,60 @@
+# Status
+
+Useful for checking if the service and database is running. The JSON output also shows
+when the database was last updated.
+
+## Parameters
+
+* `format=[text|json]` (defaults to 'text')
+
+
+## Output
+
+#### Text format
+
+```
+   https://nominatim.openstreetmap.org/status.php
+```
+
+will return HTTP status code 200 and print `OK`.
+
+On error it will return HTTP status code 500 and print a message, e.g.
+`ERROR: Database connection failed`.
+
+
+
+#### JSON format
+
+```
+   https://nominatim.openstreetmap.org/status.php?format=json
+```
+
+will return HTTP code 200 and a structure
+
+```json
+  {
+      "status": 0,
+      "message": "OK",
+      "data_updated": "2020-05-04T14:47:00+00:00"
+  }
+```
+
+On error will also return HTTP status code 200 and a structure with error
+code and message, e.g.
+
+```json
+   {
+       "status": 700,
+       "message": "Database connection failed"
+   }
+```
+
+Possible status codes are
+
+   |     | message              | notes                                             |
+   |-----|----------------------|---------------------------------------------------|
+   | 700 | "No database"        | connection failed                                 |
+   | 701 | "Module failed"      | database could not load nominatim.so              |
+   | 702 | "Module call failed" | nominatim.so loaded but calling a function failed |
+   | 703 | "Query failed"       | test query against a database table failed        |
+   | 704 | "No value"           | test query worked but returned no results         |
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 0a571f6d..d0925b7e 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -11,6 +11,7 @@ pages:
         - 'Reverse': 'api/Reverse.md'
         - 'Address Lookup': 'api/Lookup.md'
         - 'Details' : 'api/Details.md'
+        - 'Status' : 'api/Status.md'
         - 'Place Output Formats': 'api/Output.md'
         - 'FAQ': 'api/Faq.md'
     - 'Administration Guide':
-- 
2.45.2