docs/customize/Result-Formatting.md

   1 # Changing the Appearance of Results in the Server API
   2
   3 The Nominatim Server API offers a number of formatting options that
   4 present search results in [different output formats](../api/Output.md).
   5 These results only contain a subset of all the information that Nominatim
   6 has about the result. This page explains how to adapt the result output
   7 or add additional result formatting.
   8
   9 ## Defining custom result formatting
  10
  11 To change the result output, you need to place a file `api/v1/format.py`
  12 into your project directory. This file needs to define a single variable
  13 `dispatch` containing a [FormatDispatcher](#formatdispatcher). This class
  14 serves to collect the functions for formatting the different result types
  15 and offers helper functions to apply the formatters.
  16
  17 There are two ways to define the `dispatch` variable. If you want to reuse
  18 the default output formatting and just make some changes or add an additional
  19 format type, then import the dispatch object from the default API:
  20
  21 ``` python
  22 from nominatim_api.v1.format import dispatch as dispatch
  23 ```
  24
  25 If you prefer to define a completely new result output, then you can
  26 create an empty dispatcher object:
  27
  28 ``` python
  29 from nominatim_api import FormatDispatcher
  30
  31 dispatch = FormatDispatcher()
  32 ```
  33
  34 ## The formatting function
  35
  36 The dispatcher organises the formatting functions by format and result type.
  37 The format corresponds to the `format` parameter of the API. It can contain
  38 one of the predefined format names or you can invent your own new format.
  39
  40 API calls return data classes or an array of a data class which represent
  41 the result. You need to make sure there are formatters defined for the
  42 following result types:
  43
  44 * StatusResult (single object, returned by `/status`)
  45 * DetailedResult (single object, returned by `/details`)
  46 * SearchResults (list of objects, returned by `/search`)
  47 * ReverseResults (list of objects, returned by `/reverse` and `/lookup`)
  48 * RawDataList (simple object, returned by `/deletable` and `/polygons`)
  49
  50 A formatter function has the following signature:
  51
  52 ``` python
  53 def format_func(result: ResultType, options: Mapping[str, Any]) -> str
  54 ```
  55
  56 The options dictionary contains additional information about the original
  57 query. See the [reference below](#options-for-different-result-types)
  58 about the possible options.
  59
  60 To set the result formatter for a certain result type and format, you need
  61 to write the format function and decorate it with the
  62 [`format_func`](#nominatim_api.FormatDispatcher.format_func)
  63 decorator.
  64
  65 For example, let us extend the result for the status call in text format
  66 and add the server URL. Such a formatter would look like this:
  67
  68 ``` python
  69 from nominatim_api import StatusResult
  70
  71 @dispatch.format_func(StatusResult, 'text')
  72 def _format_status_text(result, _):
  73     header = 'Status for server nominatim.openstreetmap.org'
  74     if result.status:
  75         return f"{header}\n\nERROR: {result.message}"
  76
  77     return f"{header}\n\nOK"
  78 ```
  79
  80 If your dispatcher is derived from the default one, then this definition
  81 will overwrite the original formatter function. This way it is possible
  82 to customize the output of selected results.
  83
  84 ## Adding new formats
  85
  86 You may also define a completely different output format. This is as simple
  87 as adding formatting functions for all result types using the custom
  88 format name:
  89
  90 ``` python
  91 from nominatim_api import StatusResult
  92
  93 @dispatch.format_func(StatusResult, 'chatty')
  94 def _format_status_text(result, _):
  95     if result.status:
  96         return f"The server is currently not running. {result.message}"
  97
  98     return f"Good news! The server is running just fine."
  99 ```
 100
 101 That's all. Nominatim will automatically pick up the new format name and
 102 will allow the user to use it. Make sure to really define formatters for
 103 **all** result types. If they are for endpoints that you do not intend to
 104 use, you can simply return some static string but the function needs to be
 105 there.
 106
 107 All responses will be returned with the content type application/json by
 108 default. If your format produces a different content type, you need
 109 to configure the content type with the `set_content_type()` function.
 110
 111 For example, the 'chatty' format above returns just simple text. So the
 112 content type should be set up as:
 113
 114 ``` python
 115 from nominatim_api.server.content_types import CONTENT_TEXT
 116
 117 dispatch.set_content_type('chatty', CONTENT_TEXT)
 118 ```
 119
 120 The `content_types` module used above provides constants for the most
 121 frequent content types. You set the content type to an arbitrary string,
 122 if the content type you need is not available.
 123
 124 ## Reference
 125
 126 ### FormatDispatcher
 127
 128 ::: nominatim_api.FormatDispatcher
 129     options:
 130         heading_level: 6
 131         group_by_category: False
 132
 133 ### JsonWriter
 134
 135 ::: nominatim_api.utils.json_writer.JsonWriter
 136     options:
 137         heading_level: 6
 138         group_by_category: False
 139
 140 ### Options for different result types
 141
 142 This section lists the options that may be handed in with the different result
 143 types in the v1 version of the Nominatim API.
 144
 145 #### StatusResult
 146
 147 _None._
 148
 149 #### DetailedResult
 150
 151 | Option          | Description |
 152 |-----------------|-------------|
 153 | locales         | [Locale](../library/Result-Handling.md#locale) object for the requested language(s) |
 154 | group_hierarchy | Setting of [group_hierarchy](../api/Details.md#output-details) parameter |
 155 | icon_base_url   | (optional) URL pointing to icons as set in [NOMINATIM_MAPICON_URL](Settings.md#nominatim_mapicon_url) |
 156
 157 #### SearchResults
 158
 159 | Option          | Description |
 160 |-----------------|-------------|
 161 | query           | Original query string |
 162 | more_url        | URL for requesting additional results for the same query |
 163 | exclude_place_ids | List of place IDs already returned |
 164 | viewbox         | Setting of [viewbox](../api/Search.md#result-restriction) parameter |
 165 | extratags       | Setting of [extratags](../api/Search.md#output-details) parameter |
 166 | namedetails     | Setting of [namedetails](../api/Search.md#output-details) parameter |
 167 | addressdetails  | Setting of [addressdetails](../api/Search.md#output-details) parameter |
 168
 169 #### ReverseResults
 170
 171 | Option          | Description |
 172 |-----------------|-------------|
 173 | query           | Original query string |
 174 | extratags       | Setting of [extratags](../api/Search.md#output-details) parameter |
 175 | namedetails     | Setting of [namedetails](../api/Search.md#output-details) parameter |
 176 | addressdetails  | Setting of [addressdetails](../api/Search.md#output-details) parameter |
 177
 178 #### RawDataList
 179
 180 _None._