Skip to content

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.


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.


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.

GEOJSON = class-attribute instance-attribute

GeoJSON format

KML = class-attribute instance-attribute

KML format

SVG = class-attribute instance-attribute

SVG format

TEXT = class-attribute instance-attribute

WKT format

Geometry input


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.


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 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 = class-attribute instance-attribute

The address layer contains all places relevant 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 = class-attribute instance-attribute

Layer for points of interest like shops, restaurants but also recycling bins or postboxes.

RAILWAY = 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 = class-attribute instance-attribute

Layer with natural features like rivers, lakes and mountains.

MANMADE = 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.