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, 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 class GeometryFormat(enum.Flag):
  87     """ Geometry output formats supported by Nominatim.
  88     """
  89     NONE = 0
  90     GEOJSON = enum.auto()
  91     KML = enum.auto()
  92     SVG = enum.auto()
  93     TEXT = enum.auto()
  94
  95
  96 @dataclasses.dataclass
  97 class LookupDetails:
  98     """ Collection of parameters that define the amount of details
  99         returned with a search result.
 100     """
 101     geometry_output: GeometryFormat = GeometryFormat.NONE
 102     """ Add the full geometry of the place to the result. Multiple
 103         formats may be selected. Note that geometries can become quite large.
 104     """
 105     address_details: bool = False
 106     """ Get detailed information on the places that make up the address
 107         for the result.
 108     """
 109     linked_places: bool = False
 110     """ Get detailed information on the places that link to the result.
 111     """
 112     parented_places: bool = False
 113     """ Get detailed information on all places that this place is a parent
 114         for, i.e. all places for which it provides the address details.
 115         Only POI places can have parents.
 116     """
 117     keywords: bool = False
 118     """ Add information about the search terms used for this place.
 119     """