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 The following table gives an overview of the kind of features that Nominatim
  18 expects for each rank:
  19
  20 rank   | typical place types             | extent
  21 -------|---------------------------------|-------
  22 1-3    | oceans, continents              | -
  23 4      | countries                       | -
  24 5-9    | states, regions, provinces      | -
  25 10-12  | counties                        | -
  26 13-16  | cities, municipalities, islands | 7.5 km
  27 17-18  | towns, boroughs                 | 4 km
  28 19     | villages, suburbs               | 2 km
  29 20     | hamlets, farms, neighbourhoods  |  1 km
  30 21-25  | isolated dwellings, city blocks | 500 m
  31
  32 The extent column describes how far a feature is assumed to reach when it
  33 is mapped only as a point. Larger features like countries and states are usually
  34 available with their exact area in the OpenStreetMap data. That is why no extent
  35 is given.
  36
  37 ## Address rank
  38
  39 The address rank describes where a place shows up in an address hierarchy.
  40 Usually only administrative boundaries and place nodes and areas are
  41 eligible to be part of an address. Places that should not appear in the
  42 address must have an address rank of 0.
  43
  44 The following table gives an overview how ranks are mapped to address parts:
  45
  46  rank        | address part
  47 -------------|-------------
  48  1-3         | _unused_
  49  4           | country
  50  5-9         | state
  51  10-12       | county
  52  13-16       | city
  53  17-21       | suburb
  54  22-25       | neighbourhood
  55  26-27       | street
  56  28-30       | POI/house number
  57
  58 The country rank 4 usually doesn't show up in the address parts of an object.
  59 The country is determined indirectly from the country code.
  60
  61 Ranks 5-25 can be assigned more or less freely. They make up the major part
  62 of the address.
  63
  64 The street ranks 26 and 27 are handled slightly differently. Only one object
  65 from these ranks shows up in an address.
  66
  67 For POI level objects like shops, buildings or house numbers always use rank 30.
  68 Ranks 28 is reserved for house number interpolations. 29 is for internal use
  69 only.
  70
  71 ## Rank configuration
  72
  73 Search and address ranks are assigned to a place when it is first imported
  74 into the database. There are a few hard-coded rules for the assignment:
  75
  76  * postcodes follow special rules according to their length
  77  * boundaries that are not areas and railway=rail are dropped completely
  78  * the following are always search rank 30 and address rank 0:
  79     * highway nodes
  80     * landuse that is not an area
  81
  82 Other than that, the ranks can be freely assigned via the JSON file
  83 defined with `CONST_Address_Level_Config` according to their type and
  84 the country they are in.
  85
  86 The address level configuration must consist of an array of configuration
  87 entries, each containing a tag definition and an optional country array:
  88
  89 ```
  90 [ {
  91     "tags" : {
  92       "place" : {
  93         "county" : 12,
  94         "city" : 16,
  95       },
  96       "landuse" : {
  97         "residential" : 22,
  98         "" : 30
  99       }
 100     }
 101   },
 102   {
 103     "countries" : [ "ca", "us" ],
 104     "tags" : {
 105       "boundary" : {
 106         "administrative8" : 18,
 107         "administrative9" : 20
 108       },
 109       "landuse" : {
 110         "residential" : [22, 0]
 111       }
 112     }
 113   }
 114 ]
 115 ```
 116
 117 The `countries` field contains a list of countries (as ISO 3166-1 alpha 2 code)
 118 for which the definition applies. When the field is omitted, then the
 119 definition is used as a fallback, when nothing more specific for a given
 120 country exists.
 121
 122 `tags` contains the ranks for key/value pairs. The ranks can be either a
 123 single number, in which case they are the search and address rank, or an array
 124 of search and address rank (in that order). The value may be left empty.
 125 Then the rank is used when no more specific value is found for the given
 126 key.
 127
 128 Countries and key/value combination may appear in multiple definitions. Just
 129 make sure that each combination of country/key/value appears only once per
 130 file. Otherwise the import will fail with a UNIQUE INDEX constraint violation
 131 on import.
 132