-# Input parameters
+# Input Parameter Types
+
+This page describes in more detail some of the input parameter types used
+in the query functions of the API object.
## Place identification
+The [details](NominatimAPI.md#nominatim.api.core.NominatimAPI.details) and
+[lookup](NominatimAPI.md#nominatim.api.core.NominatimAPI.lookup) functions
+require references to places in the database. Below are listed the possible
+types for place identification. All types are dataclasses.
+
+### PlaceID
+
::: nominatim.api.PlaceID
options:
heading_level: 6
+### OsmID
+
::: nominatim.api.OsmID
options:
heading_level: 6
-## Geometries
+## Geometry types
::: nominatim.api.GeometryFormat
options:
heading_level: 6
+ members_order: source
+
+## Geometry input
+
+### Point
::: nominatim.api.Point
options:
heading_level: 6
+ show_signature_annotations: True
+
+### Bbox
::: nominatim.api.Bbox
options:
heading_level: 6
+ show_signature_annotations: True
+ members_order: source
+ group_by_category: False
## Layers
# Low-level connections
+The `NominatimAPIAsync` class allows to directly access the underlying
+database connection to explore the data more directly. Nominatim uses
+[SQLAlchemy](https://docs.sqlalchemy.org/) for building queries. Please
+refer to the documentation of the library to understand how to write SQL.
+
+To get access to a search connection, use the `begin()` function of your
+API object. The function returns a context manager. Use with a `with`
+statement. This returns a `SearchConnection` object described below. Its
+`t` property has definitions for all Nominatim search tables. For an
+overview of available tables, refer to the
+[Development Layout](../develop/Database-Layout.md) in in the development
+chapter. Note that only tables that are needed for search are accessible
+as SQLAlchemy tables.
+
+!!! warning
+ The database layout is not part of the API definition and may change
+ without notice. If you play with the low-level access functions, you
+ need to be prepared for such changes.
+
+Here is a simple example, which prints how many places are available in
+the placex table:
+
+```
+import asyncio
+from pathlib import Path
+import sqlalchemy as sa
+from nominatim.api import NominatimAPIAsync
+
+async def print_table_size():
+ api = NominatimAPIAsync(Path('.'))
+
+ async with api.begin() as conn:
+ cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))
+ print(f'placex table has {cnt} rows.')
+
+asyncio.run(print_table_size())
+```
+
+!!! warning
+ Low-level connections may only be used to read data from the database.
+ Do not use it to add or modify data or you might break Nominatim's
+ normal functions.
+
+## SearchConnection class
+
::: nominatim.api.SearchConnection
options:
+ members:
+ - scalar
+ - execute
+ - get_class_table
+ - get_db_property
+ - get_property
heading_level: 6
or `None` if the place could not be found in the database.
Parameters:
- place: Description of the place to look up. See PlaceRef below
+ place: Description of the place to look up. See
+ [Place identification](Input-Parameter-Types.md#place-identification)
for the various ways to reference a place.
Other parameters:
Each result is a dataclass with the fields detailed below.
Parameters:
- places: List of descriptions of the place to look up. See PlaceRef below
+ places: List of descriptions of the place to look up. See
+ [Place identification](Input-Parameter-Types.md#place-identification)
for the various ways to reference a place.
Other parameters:
@dataclasses.dataclass
class PlaceID:
- """ Reference an object by Nominatim's internal ID.
+ """ Reference a place by Nominatim's internal ID.
+
+ A PlaceID may reference place from the main table placex, from
+ the interpolation tables or the postcode tables. Place IDs are not
+ stable between installations. You may use this type theefore only
+ with place IDs obtained from the same database.
"""
place_id: int
+ """
+ The internal ID of the place to reference.
+ """
@dataclasses.dataclass
class OsmID:
- """ Reference by the OSM ID and potentially the basic category.
+ """ Reference a place by its OSM ID and potentially the basic category.
+
+ The OSM ID may refer to places in the main table placex and OSM
+ interpolation lines.
"""
osm_type: str
+ """ OSM type of the object. Must be one of `N`(node), `W`(way) or
+ `R`(relation).
+ """
osm_id: int
+ """ The OSM ID of the object.
+ """
osm_class: Optional[str] = None
+ """ The same OSM object may appear multiple times in the database under
+ different categories. The optional class parameter allows to distinguish
+ the different categories and corresponds to the key part of the category.
+ If there are multiple objects in the database and `osm_class` is
+ left out, then one of the objects is returned at random.
+ """
def __post_init__(self) -> None:
if self.osm_type not in ('N', 'W', 'R'):
WKB_BBOX_HEADER_BE = b'\x00\x20\x00\x00\x03\x00\x00\x10\xe6\x00\x00\x00\x01\x00\x00\x00\x05'
class Bbox:
- """ A bounding box in WSG84 projection.
+ """ A bounding box in WGS84 projection.
The coordinates are available as an array in the 'coord'
property in the order (minx, miny, maxx, maxy).
"""
def __init__(self, minx: float, miny: float, maxx: float, maxy: float) -> None:
+ """ Create a new bounding box with the given coordinates in WGS84
+ projection.
+ """
self.coords = (minx, miny, maxx, maxy)
@staticmethod
def from_wkb(wkb: Union[None, str, bytes]) -> 'Optional[Bbox]':
""" Create a Bbox from a bounding box polygon as returned by
- the database. Return s None if the input value is None.
+ the database. Returns `None` if the input value is None.
"""
if wkb is None:
return None
class GeometryFormat(enum.Flag):
- """ Geometry output formats supported by Nominatim.
+ """ All search functions support returning the full geometry of a place in
+ various formats. The internal geometry is converted by PostGIS to
+ the desired format and then returned as a string. It is possible to
+ request multiple formats at the same time.
"""
NONE = 0
+ """ No geometry requested. Alias for a empty flag.
+ """
GEOJSON = enum.auto()
+ """
+ [GeoJSON](https://geojson.org/) format
+ """
KML = enum.auto()
+ """
+ [KML](https://en.wikipedia.org/wiki/Keyhole_Markup_Language) format
+ """
SVG = enum.auto()
+ """
+ [SVG](http://www.w3.org/TR/SVG/paths.html) format
+ """
TEXT = enum.auto()
+ """
+ [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format
+ """
class DataLayer(enum.Flag):
projects / nominatim.git / commitdiff