Merge pull request #3593 from lonvia/order-by-bbox

[nominatim.git] / docs / library / Result-Handling.md

diff --git a/docs/library/Result-Handling.md b/docs/library/Result-Handling.md
index e2e0bc91eeab10bb12a0a80ef3c9dc333786a64f..1e8043cf9e842bd24af72d671f854d42d6f8a5c8 100644 (file)
--- a/docs/library/Result-Handling.md
+++ b/docs/library/Result-Handling.md
@@ -1,14 +1,49 @@
 # Result handling
 
-::: nominatim.api.SourceTable
+The search functions of the Nominatim API always return a result object
+with the raw information about the place that is available in the
+database. This section discusses data types used in the results and utility
+functions that allow further processing of the results.
+
+## Result fields
+
+### Sources
+
+Nominatim takes the result data from multiple sources. The `source_table` field
+in the result describes, from which source the result was retrieved.
+
+::: nominatim_api.SourceTable
     options:
         heading_level: 6
+        members_order: source
+
+### Detailed address description
 
-::: nominatim.api.AddressLine
+When the `address_details` parameter is set, then functions return not
+only information about the result place but also about the place that
+make up the address. This information is almost always required when you
+want to present the user with a human-readable description of the result.
+See also [Localization](#localization) below.
+
+The address details are available in the `address_rows` field as a ordered
+list of `AddressLine` objects with the country information last. The list also
+contains the result place itself and some artificial entries, for example,
+for the house number or the country code. This makes processing and creating
+a full address easier.
+
+::: nominatim_api.AddressLine
     options:
         heading_level: 6
+        members_order: source
+
+### Detailed search terms
+
+The `details` function can return detailed information about which search terms
+may be used to find a place, when the `keywords` parameter is set. Search
+terms are split into terms for the name of the place and search terms for
+its address.
 
-::: nominatim.api.WordInfo
+::: nominatim_api.WordInfo
     options:
         heading_level: 6
 
@@ -18,6 +53,6 @@ Results are always returned with the full list of available names.
 
 ### Locale
 
-::: nominatim.api.Locales
+::: nominatim_api.Locales
     options:
         heading_level: 6