nominatim/api/types.py

   1 # SPDX-License-Identifier: GPL-3.0-or-later
   2 #
   3 # This file is part of Nominatim. (https://nominatim.org)
   4 #
   5 # Copyright (C) 2023 by the Nominatim developer community.
   6 # For a full list of authors see the git log.
   7 """
   8 Complex datatypes used by the Nominatim API.
   9 """
  10 from typing import Optional, Union, Tuple, NamedTuple, TypeVar, Type, Dict, Any
  11 import dataclasses
  12 import enum
  13 from struct import unpack
  14
  15 from nominatim.errors import UsageError
  16
  17 @dataclasses.dataclass
  18 class PlaceID:
  19     """ Reference an object by Nominatim's internal ID.
  20     """
  21     place_id: int
  22
  23
  24 @dataclasses.dataclass
  25 class OsmID:
  26     """ Reference by the OSM ID and potentially the basic category.
  27     """
  28     osm_type: str
  29     osm_id: int
  30     osm_class: Optional[str] = None
  31
  32     def __post_init__(self) -> None:
  33         if self.osm_type not in ('N', 'W', 'R'):
  34             raise ValueError(f"Illegal OSM type '{self.osm_type}'. Must be one of N, W, R.")
  35
  36
  37 PlaceRef = Union[PlaceID, OsmID]
  38
  39
  40 class Point(NamedTuple):
  41     """ A geographic point in WGS84 projection.
  42     """
  43     x: float
  44     y: float
  45
  46
  47     @property
  48     def lat(self) -> float:
  49         """ Return the latitude of the point.
  50         """
  51         return self.y
  52
  53
  54     @property
  55     def lon(self) -> float:
  56         """ Return the longitude of the point.
  57         """
  58         return self.x
  59
  60
  61     def to_geojson(self) -> str:
  62         """ Return the point in GeoJSON format.
  63         """
  64         return f'{{"type": "Point","coordinates": [{self.x}, {self.y}]}}'
  65
  66
  67     @staticmethod
  68     def from_wkb(wkb: bytes) -> 'Point':
  69         """ Create a point from EWKB as returned from the database.
  70         """
  71         if len(wkb) != 25:
  72             raise ValueError("Point wkb has unexpected length")
  73         if wkb[0] == 0:
  74             gtype, srid, x, y = unpack('>iidd', wkb[1:])
  75         elif wkb[0] == 1:
  76             gtype, srid, x, y = unpack('<iidd', wkb[1:])
  77         else:
  78             raise ValueError("WKB has unknown endian value.")
  79
  80         if gtype != 0x20000001:
  81             raise ValueError("WKB must be a point geometry.")
  82         if srid != 4326:
  83             raise ValueError("Only WGS84 WKB supported.")
  84
  85         return Point(x, y)
  86
  87
  88 AnyPoint = Union[Point, Tuple[float, float]]
  89
  90 WKB_BBOX_HEADER_LE = b'\x01\x03\x00\x00\x20\xE6\x10\x00\x00\x01\x00\x00\x00\x05\x00\x00\x00'
  91 WKB_BBOX_HEADER_BE = b'\x00\x20\x00\x00\x03\x00\x00\x10\xe6\x00\x00\x00\x01\x00\x00\x00\x05'
  92
  93 class Bbox:
  94     """ A bounding box in WSG84 projection.
  95
  96         The coordinates are available as an array in the 'coord'
  97         property in the order (minx, miny, maxx, maxy).
  98     """
  99     def __init__(self, minx: float, miny: float, maxx: float, maxy: float) -> None:
 100         self.coords = (minx, miny, maxx, maxy)
 101
 102
 103     @property
 104     def minlat(self) -> float:
 105         """ Southern-most latitude, corresponding to the minimum y coordinate.
 106         """
 107         return self.coords[1]
 108
 109
 110     @property
 111     def maxlat(self) -> float:
 112         """ Northern-most latitude, corresponding to the maximum y coordinate.
 113         """
 114         return self.coords[3]
 115
 116
 117     @property
 118     def minlon(self) -> float:
 119         """ Western-most longitude, corresponding to the minimum x coordinate.
 120         """
 121         return self.coords[0]
 122
 123
 124     @property
 125     def maxlon(self) -> float:
 126         """ Eastern-most longitude, corresponding to the maximum x coordinate.
 127         """
 128         return self.coords[2]
 129
 130
 131     @staticmethod
 132     def from_wkb(wkb: Optional[bytes]) -> 'Optional[Bbox]':
 133         """ Create a Bbox from a bounding box polygon as returned by
 134             the database. Return s None if the input value is None.
 135         """
 136         if wkb is None:
 137             return None
 138
 139         if len(wkb) != 97:
 140             raise ValueError("WKB must be a bounding box polygon")
 141         if wkb.startswith(WKB_BBOX_HEADER_LE):
 142             x1, y1, _, _, x2, y2 = unpack('<dddddd', wkb[17:65])
 143         elif wkb.startswith(WKB_BBOX_HEADER_BE):
 144             x1, y1, _, _, x2, y2 = unpack('>dddddd', wkb[17:65])
 145         else:
 146             raise ValueError("WKB has wrong header")
 147
 148         return Bbox(min(x1, x2), min(y1, y2), max(x1, x2), max(y1, y2))
 149
 150
 151     @staticmethod
 152     def from_point(pt: Point, buffer: float) -> 'Bbox':
 153         """ Return a Bbox around the point with the buffer added to all sides.
 154         """
 155         return Bbox(pt[0] - buffer, pt[1] - buffer,
 156                     pt[0] + buffer, pt[1] + buffer)
 157
 158
 159 class GeometryFormat(enum.Flag):
 160     """ Geometry output formats supported by Nominatim.
 161     """
 162     NONE = 0
 163     GEOJSON = enum.auto()
 164     KML = enum.auto()
 165     SVG = enum.auto()
 166     TEXT = enum.auto()
 167
 168
 169 class DataLayer(enum.Flag):
 170     """ Layer types that can be selected for reverse and forward search.
 171     """
 172     POI = enum.auto()
 173     ADDRESS = enum.auto()
 174     RAILWAY = enum.auto()
 175     MANMADE = enum.auto()
 176     NATURAL = enum.auto()
 177
 178
 179 TParam = TypeVar('TParam', bound='LookupDetails') # pylint: disable=invalid-name
 180
 181 @dataclasses.dataclass
 182 class LookupDetails:
 183     """ Collection of parameters that define the amount of details
 184         returned with a lookup or details result.
 185     """
 186     geometry_output: GeometryFormat = GeometryFormat.NONE
 187     """ Add the full geometry of the place to the result. Multiple
 188         formats may be selected. Note that geometries can become quite large.
 189     """
 190     address_details: bool = False
 191     """ Get detailed information on the places that make up the address
 192         for the result.
 193     """
 194     linked_places: bool = False
 195     """ Get detailed information on the places that link to the result.
 196     """
 197     parented_places: bool = False
 198     """ Get detailed information on all places that this place is a parent
 199         for, i.e. all places for which it provides the address details.
 200         Only POI places can have parents.
 201     """
 202     keywords: bool = False
 203     """ Add information about the search terms used for this place.
 204     """
 205     geometry_simplification: float = 0.0
 206     """ Simplification factor for a geometry in degrees WGS. A factor of
 207         0.0 means the original geometry is kept. The higher the value, the
 208         more the geometry gets simplified.
 209     """
 210
 211     @classmethod
 212     def from_kwargs(cls: Type[TParam], kwargs: Dict[str, Any]) -> TParam:
 213         """ Load the data fields of the class from a dictionary.
 214             Unknown entries in the dictionary are ignored, missing ones
 215             get the default setting.
 216
 217             The function supports type checking and throws a UsageError
 218             when the value does not fit.
 219         """
 220         def _check_field(v: Any, field: 'dataclasses.Field[Any]') -> Any:
 221             if v is None:
 222                 return field.default_factory() \
 223                        if field.default_factory != dataclasses.MISSING \
 224                        else field.default
 225             if field.metadata and 'transform' in field.metadata:
 226                 return field.metadata['transform'](v)
 227             if not isinstance(v, field.type):
 228                 raise UsageError(f"Parameter '{field.name}' needs to be of {field.type!s}.")
 229             return v
 230
 231         return cls(**{f.name: _check_field(kwargs[f.name], f)
 232                       for f in dataclasses.fields(cls) if f.name in kwargs})
 233
 234
 235 @dataclasses.dataclass
 236 class ReverseDetails(LookupDetails):
 237     """ Collection of parameters for the reverse call.
 238     """
 239     max_rank: int = dataclasses.field(default=30,
 240                                       metadata={'transform': lambda v: max(0, min(v, 30))}
 241                                      )
 242     """ Highest address rank to return.
 243     """
 244     layers: DataLayer = DataLayer.ADDRESS | DataLayer.POI
 245     """ Filter which kind of data to include.
 246     """