improve display name for postcodes

[nominatim.git] / nominatim / data / place_info.py

diff --git a/nominatim/data/place_info.py b/nominatim/data/place_info.py
index 96912a61e36176900f7b557fd0e70a838af58784..91e77a588514ca4c2cd457d95286ca49883dd7e0 100644 (file)
--- a/nominatim/data/place_info.py
+++ b/nominatim/data/place_info.py
@@ -8,11 +8,11 @@
 Wrapper around place information the indexer gets from the database and hands to
 the tokenizer.
 """
 Wrapper around place information the indexer gets from the database and hands to
 the tokenizer.
 """

-from typing import Optional, Mapping, Any
+from typing import Optional, Mapping, Any, Tuple

 
 class PlaceInfo:
 
 class PlaceInfo:

-    """ Data class containing all information the tokenizer gets about a
-        place it should process the names for.
+    """ This data class contains all information the tokenizer can access
+        about a place.

     """
 
     def __init__(self, info: Mapping[str, Any]) -> None:
     """
 
     def __init__(self, info: Mapping[str, Any]) -> None:


@@ -21,16 +21,25 @@ class PlaceInfo:
 
     @property
     def name(self) -> Optional[Mapping[str, str]]:
 
     @property
     def name(self) -> Optional[Mapping[str, str]]:

-        """ A dictionary with the names of the place or None if the place
-            has no names.
+        """ A dictionary with the names of the place. Keys and values represent
+            the full key and value of the corresponding OSM tag. Which tags
+            are saved as names is determined by the import style.
+            The property may be None if the place has no names.

         """
         return self._info.get('name')
 
 
     @property
     def address(self) -> Optional[Mapping[str, str]]:
         """
         return self._info.get('name')
 
 
     @property
     def address(self) -> Optional[Mapping[str, str]]:

-        """ A dictionary with the address elements of the place
-            or None if no address information is available.
+        """ A dictionary with the address elements of the place. They key
+            usually corresponds to the suffix part of the key of an OSM
+            'addr:*' or 'isin:*' tag. There are also some special keys like
+            `country` or `country_code` which merge OSM keys that contain
+            the same information. See [Import Styles][1] for details.
+
+            The property may be None if the place has no address information.
+
+            [1]: ../customize/Import-Styles.md

         """
         return self._info.get('address')
 
         """
         return self._info.get('address')
 


@@ -38,28 +47,39 @@ class PlaceInfo:
     @property
     def country_code(self) -> Optional[str]:
         """ The country code of the country the place is in. Guaranteed
     @property
     def country_code(self) -> Optional[str]:
         """ The country code of the country the place is in. Guaranteed

-            to be a two-letter lower-case string or None, if no country
-            could be found.
+            to be a two-letter lower-case string. If the place is not inside
+            any country, the property is set to None.

         """
         return self._info.get('country_code')
 
 
     @property
     def rank_address(self) -> int:
         """
         return self._info.get('country_code')
 
 
     @property
     def rank_address(self) -> int:

-        """ The computed rank address before rank correction.
+        """ The [rank address][1] before any rank correction is applied.
+
+            [1]: ../customize/Ranking.md#address-rank

         """
         return self._info.get('rank_address', 0)
 
 
         """
         return self._info.get('rank_address', 0)
 
 

+    @property
+    def centroid(self) -> Optional[Tuple[float, float]]:
+        """ A center point of the place in WGS84. May be None when the
+            geometry of the place is unknown.
+        """
+        x, y = self._info.get('centroid_x'), self._info.get('centroid_y')
+        return None if x is None or y is None else (x, y)
+
+

     def is_a(self, key: str, value: str) -> bool:
     def is_a(self, key: str, value: str) -> bool:

-        """ Check if the place's primary tag corresponds to the given
+        """ Set to True when the place's primary tag corresponds to the given

             key and value.
         """
         return self._info.get('class') == key and self._info.get('type') == value
 
 
     def is_country(self) -> bool:
             key and value.
         """
         return self._info.get('class') == key and self._info.get('type') == value
 
 
     def is_country(self) -> bool:

-        """ Check if the place is a valid country boundary.
+        """ Set to True when the place is a valid country boundary.

         """
         return self.rank_address == 4 \
                and self.is_a('boundary', 'administrative') \
         """
         return self.rank_address == 4 \
                and self.is_a('boundary', 'administrative') \