Merge remote-tracking branch 'upstream/master'

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

diff --git a/docs/develop/Ranking.md b/docs/develop/Ranking.md
index 037049373662e72d94d7178595f62cb1c208ced0..06f255004dcbc3b8cf272303da96880e3abc3c2a 100644 (file)
--- a/docs/develop/Ranking.md
+++ b/docs/develop/Ranking.md
@@ -14,17 +14,67 @@ 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.
 
 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
 ## 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 place 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
 
 
 ## Rank configuration
 


@@ -37,7 +87,7 @@ into the database. There are a few hard-coded rules for the assignment:
     * highway nodes
     * landuse that is not an area
 
     * highway nodes
     * landuse that is not an area
 

-Other than that, the ranks can be freely assigned via the json file
+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.
 
 defined with `CONST_Address_Level_Config` according to their type and
 the country they are in.
 


@@ -78,12 +128,13 @@ definition is used as a fallback, when nothing more specific for a given
 country exists.
 
 `tags` contains the ranks for key/value pairs. The ranks can be either a
 country exists.
 
 `tags` contains the ranks for key/value pairs. The ranks can be either a

-single number, in which case they are to search and address rank, or a tuple
+single number, in which case they are the search and address rank, or an array

 of search and address rank (in that order). The value may be left empty.
 Then the rank is used when no more specific value is found for the given
 key.
 
 of search and address rank (in that order). The value may be left empty.
 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 defintions. Just
-make sure that each combination of counrty/key/value appears only once per
+Countries and key/value combination may appear in multiple definitions. Just
+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.
 file. Otherwise the import will fail with a UNIQUE INDEX constraint violation
 on import.

+