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
  14 @dataclasses.dataclass
  15 class PlaceID:
  16     """ Reference an object by Nominatim's internal ID.
  17     """
  18     place_id: int
  19
  20
  21 @dataclasses.dataclass
  22 class OsmID:
  23     """ Reference by the OSM ID and potentially the basic category.
  24     """
  25     osm_type: str
  26     osm_id: int
  27     osm_class: Optional[str] = None
  28
  29     def __post_init__(self) -> None:
  30         if self.osm_type not in ('N', 'W', 'R'):
  31             raise ValueError(f"Illegal OSM type '{self.osm_type}'. Must be one of N, W, R.")
  32
  33
  34 PlaceRef = Union[PlaceID, OsmID]
  35
  36
  37 class Point(NamedTuple):
  38     """ A geographic point in WGS84 projection.
  39     """
  40     x: float
  41     y: float
  42
  43
  44     @property
  45     def lat(self) -> float:
  46         """ Return the latitude of the point.
  47         """
  48         return self.y
  49
  50
  51     @property
  52     def lon(self) -> float:
  53         """ Return the longitude of the point.
  54         """
  55         return self.x
  56
  57
  58 class GeometryFormat(enum.Flag):
  59     """ Geometry output formats supported by Nominatim.
  60     """
  61     NONE = 0
  62     GEOJSON = enum.auto()
  63     KML = enum.auto()
  64     SVG = enum.auto()
  65     TEXT = enum.auto()
  66
  67
  68 @dataclasses.dataclass
  69 class LookupDetails:
  70     """ Collection of parameters that define the amount of details
  71         returned with a search result.
  72     """
  73     geometry_output: GeometryFormat = GeometryFormat.NONE
  74     """ Add the full geometry of the place to the result. Multiple
  75         formats may be selected. Note that geometries can become quite large.
  76     """
  77     address_details: bool = False
  78     """ Get detailed information on the places that make up the address
  79         for the result.
  80     """
  81     linked_places: bool = False
  82     """ Get detailed information on the places that link to the result.
  83     """
  84     parented_places: bool = False
  85     """ Get detailed information on all places that this place is a parent
  86         for, i.e. all places for which it provides the address details.
  87         Only POI places can have parents.
  88     """
  89     keywords: bool = False
  90     """ Add information about the search terms used for this place.
  91     """