docs/api/Status.md

   1 # Status
   2
   3 Report on the state of the service and database. Useful for checking if the
   4 service is up and running. The JSON output also reports
   5 when the database was last updated.
   6
   7 ## Endpoint
   8
   9 The status API has the following format:
  10
  11 ```
  12 https://nominatim.openstreetmap.org/status
  13 ```
  14
  15 !!! danger "Deprecation warning"
  16     The API can also be used with the URL
  17     `https://nominatim.openstreetmap.org/status.php`. This is now deprecated
  18     and will be removed in future versions.
  19
  20
  21 ## Parameters
  22
  23 The status endpoint takes a single optional parameter:
  24
  25 | Parameter | Value | Default |
  26 |-----------| ----- | ------- |
  27 | format    | one of: `text`, `json` | 'text' |
  28
  29 Selects the output format. See below.
  30
  31
  32 ## Output
  33
  34 #### Text format
  35
  36 When everything is okay, a status code 200 is returned and a simple message: `OK`
  37
  38 On error it will return HTTP status code 500 and print a detailed error message, e.g.
  39 `ERROR: Database connection failed`.
  40
  41
  42
  43 #### JSON format
  44
  45 Always returns a HTTP code 200, when the status call could be executed.
  46
  47 On success a JSON dictionary with the following structure is returned:
  48
  49 ```json
  50   {
  51       "status": 0,
  52       "message": "OK",
  53       "data_updated": "2020-05-04T14:47:00+00:00",
  54       "software_version": "3.6.0-0",
  55       "database_version": "3.6.0-0"
  56   }
  57 ```
  58
  59 The `software_version` field contains the version of Nominatim used to serve
  60 the API. The `database_version` field contains the version of the data format
  61 in the database.
  62
  63 On error will return a shorter JSON dictionary with the error message
  64 and status only, e.g.
  65
  66 ```json
  67    {
  68        "status": 700,
  69        "message": "Database connection failed"
  70    }
  71 ```