docs/library/Result-Handling.md

   1 # Result handling
   2
   3 The search functions of the Nominatim API always return a result object
   4 with the raw information about the place that is available in the
   5 database. This section discusses data types used in the results and utility
   6 functions that allow further processing of the results.
   7
   8 ## Result fields
   9
  10 ### Sources
  11
  12 Nominatim takes the result data from multiple sources. The `source_table` field
  13 in the result describes, from which source the result was retrieved.
  14
  15 ::: nominatim_api.SourceTable
  16     options:
  17         heading_level: 6
  18         members_order: source
  19
  20 ### Detailed address description
  21
  22 When the `address_details` parameter is set, then functions return not
  23 only information about the result place but also about the place that
  24 make up the address. This information is almost always required when you
  25 want to present the user with a human-readable description of the result.
  26 See also [Localization](#localization) below.
  27
  28 The address details are available in the `address_rows` field as a ordered
  29 list of `AddressLine` objects with the country information last. The list also
  30 contains the result place itself and some artificial entries, for example,
  31 for the house number or the country code. This makes processing and creating
  32 a full address easier.
  33
  34 ::: nominatim_api.AddressLine
  35     options:
  36         heading_level: 6
  37         members_order: source
  38
  39 ### Detailed search terms
  40
  41 The `details` function can return detailed information about which search terms
  42 may be used to find a place, when the `keywords` parameter is set. Search
  43 terms are split into terms for the name of the place and search terms for
  44 its address.
  45
  46 ::: nominatim_api.WordInfo
  47     options:
  48         heading_level: 6
  49
  50 ## Localization
  51
  52 Results are always returned with the full list of available names. However, the
  53 default `locale_name` must be explicitly set using the `localize` function within
  54 `Locales`. This parses through the full list of available names to find the one
  55 most preferred by the user. Once this is set, the user can simply use the
  56 `display_name` field within a `Result` object to retrive the localized name.
  57
  58 ### Locale
  59
  60 ::: nominatim_api.Locales
  61     options:
  62         heading_level: 6