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 WKB_BBOX_HEADER_LE = b'\x01\x03\x00\x00\x20\xE6\x10\x00\x00\x01\x00\x00\x00\x05\x00\x00\x00'
  89 WKB_BBOX_HEADER_BE = b'\x00\x20\x00\x00\x03\x00\x00\x10\xe6\x00\x00\x00\x01\x00\x00\x00\x05'
  90
  91 class Bbox:
  92     """ A bounding box in WSG84 projection.
  93
  94         The coordinates are available as an array in the 'coord'
  95         property in the order (minx, miny, maxx, maxy).
  96     """
  97     def __init__(self, minx: float, miny: float, maxx: float, maxy: float) -> None:
  98         self.coords = (minx, miny, maxx, maxy)
  99
 100
 101     @property
 102     def minlat(self) -> float:
 103         """ Southern-most latitude, corresponding to the minimum y coordinate.
 104         """
 105         return self.coords[1]
 106
 107
 108     @property
 109     def maxlat(self) -> float:
 110         """ Northern-most latitude, corresponding to the maximum y coordinate.
 111         """
 112         return self.coords[3]
 113
 114
 115     @property
 116     def minlon(self) -> float:
 117         """ Western-most longitude, corresponding to the minimum x coordinate.
 118         """
 119         return self.coords[0]
 120
 121
 122     @property
 123     def maxlon(self) -> float:
 124         """ Eastern-most longitude, corresponding to the maximum x coordinate.
 125         """
 126         return self.coords[2]
 127
 128
 129     @staticmethod
 130     def from_wkb(wkb: Optional[bytes]) -> 'Optional[Bbox]':
 131         """ Create a Bbox from a bounding box polygon as returned by
 132             the database. Return s None if the input value is None.
 133         """
 134         if wkb is None:
 135             return None
 136
 137         if len(wkb) != 97:
 138             raise ValueError("WKB must be a bounding box polygon")
 139         if wkb.startswith(WKB_BBOX_HEADER_LE):
 140             x1, y1, _, _, x2, y2 = unpack('<dddddd', wkb[17:65])
 141         elif wkb.startswith(WKB_BBOX_HEADER_BE):
 142             x1, y1, _, _, x2, y2 = unpack('>dddddd', wkb[17:65])
 143         else:
 144             raise ValueError("WKB has wrong header")
 145
 146         return Bbox(min(x1, x2), min(y1, y2), max(x1, x2), max(y1, y2))
 147
 148
 149     @staticmethod
 150     def from_point(pt: Point, buffer: float) -> 'Bbox':
 151         """ Return a Bbox around the point with the buffer added to all sides.
 152         """
 153         return Bbox(pt[0] - buffer, pt[1] - buffer,
 154                     pt[0] + buffer, pt[1] + buffer)
 155
 156
 157 class GeometryFormat(enum.Flag):
 158     """ Geometry output formats supported by Nominatim.
 159     """
 160     NONE = 0
 161     GEOJSON = enum.auto()
 162     KML = enum.auto()
 163     SVG = enum.auto()
 164     TEXT = enum.auto()
 165
 166
 167 @dataclasses.dataclass
 168 class LookupDetails:
 169     """ Collection of parameters that define the amount of details
 170         returned with a search result.
 171     """
 172     geometry_output: GeometryFormat = GeometryFormat.NONE
 173     """ Add the full geometry of the place to the result. Multiple
 174         formats may be selected. Note that geometries can become quite large.
 175     """
 176     address_details: bool = False
 177     """ Get detailed information on the places that make up the address
 178         for the result.
 179     """
 180     linked_places: bool = False
 181     """ Get detailed information on the places that link to the result.
 182     """
 183     parented_places: bool = False
 184     """ Get detailed information on all places that this place is a parent
 185         for, i.e. all places for which it provides the address details.
 186         Only POI places can have parents.
 187     """
 188     keywords: bool = False
 189     """ Add information about the search terms used for this place.
 190     """
 191     geometry_simplification: float = 0.0
 192     """ Simplification factor for a geometry in degrees WGS. A factor of
 193         0.0 means the original geometry is kept. The higher the value, the
 194         more the geometry gets simplified.
 195     """
 196
 197
 198 class DataLayer(enum.Flag):
 199     """ Layer types that can be selected for reverse and forward search.
 200     """
 201     POI = enum.auto()
 202     ADDRESS = enum.auto()
 203     RAILWAY = enum.auto()
 204     MANMADE = enum.auto()
 205     NATURAL = enum.auto()