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
  11 import dataclasses
  12 import enum
  13 from struct import unpack
  14
  15 @dataclasses.dataclass
  16 class PlaceID:
  17     """ Reference an object by Nominatim's internal ID.
  18     """
  19     place_id: int
  20
  21
  22 @dataclasses.dataclass
  23 class OsmID:
  24     """ Reference by the OSM ID and potentially the basic category.
  25     """
  26     osm_type: str
  27     osm_id: int
  28     osm_class: Optional[str] = None
  29
  30     def __post_init__(self) -> None:
  31         if self.osm_type not in ('N', 'W', 'R'):
  32             raise ValueError(f"Illegal OSM type '{self.osm_type}'. Must be one of N, W, R.")
  33
  34
  35 PlaceRef = Union[PlaceID, OsmID]
  36
  37
  38 class Point(NamedTuple):
  39     """ A geographic point in WGS84 projection.
  40     """
  41     x: float
  42     y: float
  43
  44
  45     @property
  46     def lat(self) -> float:
  47         """ Return the latitude of the point.
  48         """
  49         return self.y
  50
  51
  52     @property
  53     def lon(self) -> float:
  54         """ Return the longitude of the point.
  55         """
  56         return self.x
  57
  58
  59     def to_geojson(self) -> str:
  60         """ Return the point in GeoJSON format.
  61         """
  62         return f'{{"type": "Point","coordinates": [{self.x}, {self.y}]}}'
  63
  64
  65     @staticmethod
  66     def from_wkb(wkb: bytes) -> 'Point':
  67         """ Create a point from EWKB as returned from the database.
  68         """
  69         if len(wkb) != 25:
  70             raise ValueError("Point wkb has unexpected length")
  71         if wkb[0] == 0:
  72             gtype, srid, x, y = unpack('>iidd', wkb[1:])
  73         elif wkb[0] == 1:
  74             gtype, srid, x, y = unpack('<iidd', wkb[1:])
  75         else:
  76             raise ValueError("WKB has unknown endian value.")
  77
  78         if gtype != 0x20000001:
  79             raise ValueError("WKB must be a point geometry.")
  80         if srid != 4326:
  81             raise ValueError("Only WGS84 WKB supported.")
  82
  83         return Point(x, y)
  84
  85
  86 AnyPoint = Union[Point, Tuple[float, float]]
  87
  88
  89 class Bbox:
  90     """ A bounding box in WSG84 projection.
  91
  92         The coordinates are available as an array in the 'coord'
  93         property in the order (minx, miny, maxx, maxy).
  94     """
  95     def __init__(self, minx: float, miny: float, maxx: float, maxy: float) -> None:
  96         self.coords = (minx, miny, maxx, maxy)
  97
  98
  99     @property
 100     def minlat(self) -> float:
 101         """ Southern-most latitude, corresponding to the minimum y coordinate.
 102         """
 103         return self.coords[1]
 104
 105
 106     @property
 107     def maxlat(self) -> float:
 108         """ Northern-most latitude, corresponding to the maximum y coordinate.
 109         """
 110         return self.coords[3]
 111
 112
 113     @property
 114     def minlon(self) -> float:
 115         """ Western-most longitude, corresponding to the minimum x coordinate.
 116         """
 117         return self.coords[0]
 118
 119
 120     @property
 121     def maxlon(self) -> float:
 122         """ Eastern-most longitude, corresponding to the maximum x coordinate.
 123         """
 124         return self.coords[2]
 125
 126
 127     @staticmethod
 128     def from_wkb(wkb: Optional[bytes]) -> 'Optional[Bbox]':
 129         """ Create a Bbox from a bounding box polygon as returned by
 130             the database. Return s None if the input value is None.
 131         """
 132         if wkb is None:
 133             return None
 134
 135         if len(wkb) != 97:
 136             raise ValueError("WKB must be a bounding box polygon")
 137         if wkb.startswith(b'\x01\x03\x00\x00\x20\xE6\x10\x00\x00\x01\x00\x00\x00\x05\x00\x00\x00'):
 138             x1, y1, _, _, x2, y2 = unpack('<dddddd', wkb[17:65])
 139         elif wkb.startswith(b'\x00\x20\x00\x00\x03\x00\x00\x10\xe6\x00\x00\x00\x01\x00\x00\x00\x05'):
 140             x1, y1, _, _, x2, y2 = unpack('>dddddd', wkb[17:65])
 141         else:
 142             raise ValueError("WKB has wrong header")
 143
 144         return Bbox(min(x1, x2), min(y1, y2), max(x1, x2), max(y1, y2))
 145
 146
 147     def from_point(pt: Point, buffer: float) -> 'Bbox':
 148         """ Return a Bbox around the point with the buffer added to all sides.
 149         """
 150         return Bbox(pt[0] - buffer, pt[1] - buffer,
 151                     pt[0] + buffer, pt[1] + buffer)
 152
 153
 154 class GeometryFormat(enum.Flag):
 155     """ Geometry output formats supported by Nominatim.
 156     """
 157     NONE = 0
 158     GEOJSON = enum.auto()
 159     KML = enum.auto()
 160     SVG = enum.auto()
 161     TEXT = enum.auto()
 162
 163
 164 @dataclasses.dataclass
 165 class LookupDetails:
 166     """ Collection of parameters that define the amount of details
 167         returned with a search result.
 168     """
 169     geometry_output: GeometryFormat = GeometryFormat.NONE
 170     """ Add the full geometry of the place to the result. Multiple
 171         formats may be selected. Note that geometries can become quite large.
 172     """
 173     address_details: bool = False
 174     """ Get detailed information on the places that make up the address
 175         for the result.
 176     """
 177     linked_places: bool = False
 178     """ Get detailed information on the places that link to the result.
 179     """
 180     parented_places: bool = False
 181     """ Get detailed information on all places that this place is a parent
 182         for, i.e. all places for which it provides the address details.
 183         Only POI places can have parents.
 184     """
 185     keywords: bool = False
 186     """ Add information about the search terms used for this place.
 187     """
 188     geometry_simplification: float = 0.0
 189     """ Simplification factor for a geometry in degrees WGS. A factor of
 190         0.0 means the original geometry is kept. The higher the value, the
 191         more the geometry gets simplified.
 192     """
 193
 194
 195 class DataLayer(enum.Flag):
 196     """ Layer types that can be selected for reverse and forward search.
 197     """
 198     POI = enum.auto()
 199     ADDRESS = enum.auto()
 200     RAILWAY = enum.auto()
 201     MANMADE = enum.auto()
 202     NATURAL = enum.auto()