docs/develop/Ranking.md

   1 # Place Ranking in Nominatim
   2
   3 Nominatim uses two metrics to rank a place: search rank and address rank.
   4 Both can be assigned a value between 0 and 30. They serve slightly
   5 different purposes, which are explained in this chapter.
   6
   7 ## Search rank
   8
   9 The search rank describes the extent and importance of a place. It is used
  10 when ranking search result. Simply put, if there are two results for a
  11 search query which are otherwise equal, then the result with the _lower_
  12 search rank will be appear higher in the result list.
  13
  14 Search ranks are not so important these days because many well-known
  15 places use the Wikipedia importance ranking instead.
  16
  17 ## Address rank
  18
  19 The address rank describes where a place shows up in an address hierarchy.
  20 Usually only administrative boundaries and place nodes and areas are
  21 eligible to be part of an address. All other objects have an address rank
  22 of 0.
  23
  24 Note that the search rank of a place plays a role in the address computation
  25 as well. When collecting the places that should make up the address parts
  26 then only places are taken into account that have a lower address rank than
  27 the search rank of the base object.
  28
  29 ## Rank configuration
  30
  31 Search and address ranks are assigned to a place when it is first imported
  32 into the database. There are a few hard-coded rules for the assignment:
  33
  34  * postcodes follow special rules according to their length
  35  * boundaries that are not areas and railway=rail are dropped completely
  36  * the following are always search rank 30 and address rank 0:
  37     * highway nodes
  38     * landuse that is not an area
  39
  40 Other than that, the ranks can be freely assigned via the JSON file
  41 defined with `CONST_Address_Level_Config` according to their type and
  42 the country they are in.
  43
  44 The address level configuration must consist of an array of configuration
  45 entries, each containing a tag definition and an optional country array:
  46
  47 ```
  48 [ {
  49     "tags" : {
  50       "place" : {
  51         "county" : 12,
  52         "city" : 16,
  53       },
  54       "landuse" : {
  55         "residential" : 22,
  56         "" : 30
  57       }
  58     }
  59   },
  60   {
  61     "countries" : [ "ca", "us" ],
  62     "tags" : {
  63       "boundary" : {
  64         "administrative8" : 18,
  65         "administrative9" : 20
  66       },
  67       "landuse" : {
  68         "residential" : [22, 0]
  69       }
  70     }
  71   }
  72 ]
  73 ```
  74
  75 The `countries` field contains a list of countries (as ISO 3166-1 alpha 2 code)
  76 for which the definition applies. When the field is omitted, then the
  77 definition is used as a fallback, when nothing more specific for a given
  78 country exists.
  79
  80 `tags` contains the ranks for key/value pairs. The ranks can be either a
  81 single number, in which case they are the search and address rank, or an array
  82 of search and address rank (in that order). The value may be left empty.
  83 Then the rank is used when no more specific value is found for the given
  84 key.
  85
  86 Countries and key/value combination may appear in multiple definitions. Just
  87 make sure that each combination of counrty/key/value appears only once per
  88 file. Otherwise the import will fail with a UNIQUE INDEX constraint violation
  89 on import.
  90