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 and lookup functions require references to places in the database. Below the possible types for place identification are listed. All types are dataclasses.
PlaceID
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
instance-attribute
The internal ID of the place to reference.
OsmID
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_class: Optional[str] = None
class-attribute
instance-attribute
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.
osm_id: int
instance-attribute
The OSM ID of the object.
osm_type: str
instance-attribute
OSM type of the object. Must be one of N(node), W(way) or
R(relation).
Geometry types
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
class-attribute
instance-attribute
No geometry requested. Alias for a empty flag.
Geometry input
Point
A geographic point in WGS84 projection.
lat: float
property
Return the latitude of the point.
lon: float
property
Return the longitude of the point.
from_param(inp: Any) -> Point
staticmethod
Create a point from an input parameter. The parameter may be given as a point, a string or a sequence of strings or floats. Raises a UsageError if the format is not correct.
from_wkb(wkb: Union[str, bytes]) -> Point
staticmethod
Create a point from EWKB as returned from the database.
to_geojson() -> str
Return the point in GeoJSON format.
to_wkt() -> str
Return the WKT representation of the point.
Bbox
A bounding box in WGS84 projection.
The coordinates are available as an array in the 'coord' property in the order (minx, miny, maxx, maxy).
__init__(minx: float, miny: float, maxx: float, maxy: float) -> None
Create a new bounding box with the given coordinates in WGS84 projection.
minlat: float
property
Southern-most latitude, corresponding to the minimum y coordinate.
maxlat: float
property
Northern-most latitude, corresponding to the maximum y coordinate.
minlon: float
property
Western-most longitude, corresponding to the minimum x coordinate.
maxlon: float
property
Eastern-most longitude, corresponding to the maximum x coordinate.
area: float
property
Return the area of the box in WGS84.
contains(pt: Point) -> bool
Check if the point is inside or on the boundary of the box.
to_wkt() -> str
Return the WKT representation of the Bbox. This is a simple polygon with four points.
from_wkb(wkb: Union[None, str, bytes]) -> Optional[Bbox]
staticmethod
Create a Bbox from a bounding box polygon as returned by
the database. Returns None if the input value is None.
from_point(pt: Point, buffer: float) -> Bbox
staticmethod
Return a Bbox around the point with the buffer added to all sides.
from_param(inp: Any) -> Bbox
staticmethod
Return a Bbox from an input parameter. The box may be given as a Bbox, a string or a list or strings or integer. Raises a UsageError if the format is incorrect.
Layers
Layers allow to restrict the search result to thematic groups. This is orthogonal to restriction by address ranks, which groups places by their geographic extent.
The DataLayer flag type defines the layers that can be selected
for reverse and forward search.
ADDRESS = enum.auto()
class-attribute
instance-attribute
The address layer contains all places relavant for addresses: fully qualified addresses with a house number (or a house name equivalent, for some addresses) and places that can be part of an address like roads, cities, states.
POI = enum.auto()
class-attribute
instance-attribute
Layer for points of interest like shops, restaurants but also recycling bins or postboxes.
RAILWAY = enum.auto()
class-attribute
instance-attribute
Layer with railway features including tracks and other infrastructure. Note that in Nominatim's standard configuration, only very few railway features are imported into the database. Thus a custom configuration is required to make full use of this layer.
NATURAL = enum.auto()
class-attribute
instance-attribute
Layer with natural features like rivers, lakes and mountains.
MANMADE = enum.auto()
class-attribute
instance-attribute
Layer with other human-made features and boundaries. This layer is the catch-all and includes all features not covered by the other layers. A typical example for this layer are national park boundaries.