Merge pull request #2136 from lonvia/introduce-pylint

[nominatim.git] / docs / develop / Ranking.md

diff --git a/docs/develop/Ranking.md b/docs/develop/Ranking.md
index 776de8f571d6387bd74004864ebeb13628bc47dc..5b1ca1915ca653624261278c04adffa65cbc9882 100644 (file)
--- a/docs/develop/Ranking.md
+++ b/docs/develop/Ranking.md
@@ -7,24 +7,74 @@ different purposes, which are explained in this chapter.
 ## Search rank
 
 The search rank describes the extent and importance of a place. It is used
-when ranking search result. Simply put, if there are two results for a
+when ranking search results. Simply put, if there are two results for a
 search query which are otherwise equal, then the result with the _lower_
 search rank will be appear higher in the result list.
 
 Search ranks are not so important these days because many well-known
 places use the Wikipedia importance ranking instead.
 
+The following table gives an overview of the kind of features that Nominatim
+expects for each rank:
+
+rank   | typical place types             | extent
+-------|---------------------------------|-------
+1-3    | oceans, continents              | -
+4      | countries                       | -
+5-9    | states, regions, provinces      | -
+10-12  | counties                        | -
+13-16  | cities, municipalities, islands | 15 km
+17-18  | towns, boroughs                 | 4 km
+19     | villages, suburbs               | 2 km
+20     | hamlets, farms, neighbourhoods  |  1 km
+21-25  | isolated dwellings, city blocks | 500 m
+
+The extent column describes how far a feature is assumed to reach when it
+is mapped only as a point. Larger features like countries and states are usually
+available with their exact area in the OpenStreetMap data. That is why no extent
+is given.
+
 ## Address rank
 
 The address rank describes where a place shows up in an address hierarchy.
 Usually only administrative boundaries and place nodes and areas are
-eligible to be part of an address. All other objects have an address rank
-of 0.
-
-Note that the search rank of a place plays a role in the address computation
-as well. When collecting the places that should make up the address parts
-then only places are taken into account that have a lower address rank than
-the search rank of the base object.
+eligible to be part of an address. Places that should not appear in the
+address must have an address rank of 0.
+
+The following table gives an overview how ranks are mapped to address parts:
+
+ rank        | address part
+-------------|-------------
+ 1-3         | _unused_
+ 4           | country
+ 5-9         | state
+ 10-12       | county
+ 13-16       | city
+ 17-21       | suburb
+ 22-24       | neighbourhood
+ 25          | squares, farms, localities
+ 26-27       | street
+ 28-30       | POI/house number
+
+The country rank 4 usually doesn't show up in the address parts of an object.
+The country is determined indirectly from the country code.
+
+Ranks 5-24 can be assigned more or less freely. They make up the major part
+of the address.
+
+Rank 25 is also an addressing rank but it is special because while it can be
+the parent to a POI with an addr:place of the same name, it cannot be a parent
+to streets. Use it for place features that are technically on the same level
+as a street (e.g. squares, city blocks) or for places that should not normally
+appear in an address unless explicitly tagged so (e.g place=locality which
+should be uninhabited and as such not addressable).
+
+The street ranks 26 and 27 are handled slightly differently. Only one object
+from these ranks shows up in an address.
+
+For POI level objects like shops, buildings or house numbers always use rank 30.
+Ranks 28 is reserved for house number interpolations. 29 is for internal use
+only.
 
 ## Rank configuration
 
@@ -37,9 +87,9 @@ into the database. There are a few hard-coded rules for the assignment:
     * highway nodes
     * landuse that is not an area
 
-Other than that, the ranks can be freely assigned via the JSON file
-defined with `CONST_Address_Level_Config` according to their type and
-the country they are in.
+Other than that, the ranks can be freely assigned via the JSON file according
+to their type and the country they are in. The name of the config file to be
+used can be changed with the setting `NOMINATIM_ADDRESS_LEVEL_CONFIG`.
 
 The address level configuration must consist of an array of configuration
 entries, each containing a tag definition and an optional country array:
@@ -84,7 +134,7 @@ Then the rank is used when no more specific value is found for the given
 key.
 
 Countries and key/value combination may appear in multiple definitions. Just
-make sure that each combination of counrty/key/value appears only once per
+make sure that each combination of country/key/value appears only once per
 file. Otherwise the import will fail with a UNIQUE INDEX constraint violation
 on import.