The Nominatim API classes

The API classes are the core object of the search library. Always instantiate one of these classes first. The API classes are not threadsafe. You need to instantiate a separate instance for each thread.

NominatimAPI

This class provides a thin synchronous wrapper around the asynchronous Nominatim functions. It creates its own event loop and runs each synchronous function call to completion using that loop.

This class should usually be used as a context manager in 'with' context.

__init__(project_dir=None, environ=None)

Initiate a new frontend object with synchronous API functions.

Parameters:

Name	Type	Description	Default
project_dir	Optional[Union[str, Path]]	Path to the project directory of the local Nominatim installation.	None
environ	Optional[Mapping[str, str]]	Mapping of configuration parameters. When set, replaces any configuration via environment variables. Settings in this mapping also have precedence over any parameters found in the .env file of the project directory.	None

config: Configuration property

Provide read-only access to the configuration used by the API.

close()

Close all active connections to the database.

This function also closes the asynchronous worker loop making the NominatimAPI object unusable.

status()

Return the status of the database as a dataclass object with the fields described below.

Returns:

Name	Type	Description
status	int	A status code as described on the status page.
message	str	Either 'OK' or a human-readable message of the problem encountered.
software_version	tuple	A tuple with the version of the Nominatim library consisting of (major, minor, patch, db-patch) version.
database_version	tuple	A tuple with the version of the library which was used for the import or last migration. Also consists of (major, minor, patch, db-patch).
data_updated	datetime	Timestamp with the age of the data.

details(place, **params)

Get detailed information about a place in the database.

The result is a dataclass object with the fields described below or None if the place could not be found in the database.

Parameters:

Name	Type	Description	Default
place	PlaceRef	Description of the place to look up. See Place identification for the various ways to reference a place.	required

Other Parameters:

Name	Type	Description
geometry_output	enum	Add the full geometry of the place to the result. Multiple formats may be selected. Note that geometries can become quite large. (Default: none)
geometry_simplification	float	Simplification factor to use on the geometries before returning them. The factor expresses the tolerance in degrees from which the geometry may differ. Topology is preserved. (Default: 0.0)
address_details	bool	Add detailed information about the places that make up the address of the requested object. (Default: False)
linked_places	bool	Add detailed information about the places that link to the result. (Default: False)
parented_places	bool	Add detailed information about all places for which the requested object is a parent, i.e. all places for which the object provides the address details. Only POI places can have parents. (Default: False)
keywords	bool	Add detailed information about the search terms used for this place.

Returns:

Name	Type	Description
source_table	enum	Data source of the place. See below for possible values.
category	tuple	A tuple of two strings with the primary OSM tag and value.
centroid	Point	Point position of the place.
place_id	Optional[int]	Internal ID of the place. This ID may differ for the same place between different installations.
parent_place_id	Optional(int]	Internal ID of the parent of this place. Only meaning full for POI-like objects (places with a rank_address of 30).
linked_place_id	Optional[int]	Internal ID of the place this object links to. When this ID is set then there is no guarantee that the rest of the result information is complete.
admin_level	int	Value of the admin_level OSM tag. Only meaningful for administrative boundary objects.
indexed_date	datetime	Timestamp when the place was last updated.
osm_object	Optional[tuple]	OSM type and ID of the place, if available.
names	Optional[dict]	Dictionary of names of the place. Keys are usually the corresponding OSM tag keys.
address	Optional[dict]	Dictionary of address parts directly attributed to the place. Keys are usually the corresponding OSM tag keys with the addr: prefix removed.
extratags	Optional[dict]	Dictionary of additional attributes for the place. Usually OSM tag keys and values.
housenumber	Optional[str]	House number of the place, normalised for lookup. To get the house number in its original spelling, use address['housenumber'].
postcode	Optional[str]	Computed postcode for the place. To get directly attributed postcodes, use address['postcode'] instead.
wikipedia	Optional[str]	Reference to a wikipedia site for the place. The string has the format :.
rank_address	int	Address rank.
rank_search	int	Search rank.
importance	Optional[float]	Relative importance of the place. This is a measure how likely the place will be searched for.
country_code	Optional[str]	Country the feature is in as ISO 3166-1 alpha-2 country code.
address_rows	Optional[AddressLines]	List of places that make up the computed address. None when address_details parameter was False.
linked_rows	Optional[AddressLines]	List of places that link to the object. None when linked_places parameter was False.
parented_rows	Optional[AddressLines]	List of direct children of the place. None when parented_places parameter was False.
name_keywords	Optional[WordInfos]	List of search words for the name of the place. None when keywords parameter is set to False.
address_keywords	Optional[WordInfos]	List of search word for the address of the place. None when keywords parameter is set to False.
geometry	dict	Dictionary containing the full geometry of the place in the formats requested in the geometry_output parameter.

lookup(places, **params)

Get simple information about a list of places.

Returns a list of place information for all IDs that were found. Each result is a dataclass with the fields detailed below.

Parameters:

Name	Type	Description	Default
places	Sequence[types.PlaceRef]	List of descriptions of the place to look up. See Place identification for the various ways to reference a place.	required

Other Parameters:

Name	Type	Description
geometry_output	enum	Add the full geometry of the place to the result. Multiple formats may be selected. Note that geometries can become quite large. (Default: none)
geometry_simplification	float	Simplification factor to use on the geometries before returning them. The factor expresses the tolerance in degrees from which the geometry may differ. Topology is preserved. (Default: 0.0)
address_details	bool	Add detailed information about the places that make up the address of the requested object. (Default: False)
linked_places	bool	Add detailed information about the places that link to the result. (Default: False)
parented_places	bool	Add detailed information about all places for which the requested object is a parent, i.e. all places for which the object provides the address details. Only POI places can have parents. (Default: False)
keywords	bool	Add detailed information about the search terms used for this place.

Returns:

Name	Type	Description
source_table	enum	Data source of the place. See below for possible values.
category	tuple	A tuple of two strings with the primary OSM tag and value.
centroid	Point	Point position of the place.
place_id	Optional[int]	Internal ID of the place. This ID may differ for the same place between different installations.
osm_object	Optional[tuple]	OSM type and ID of the place, if available.
names	Optional[dict]	Dictionary of names of the place. Keys are usually the corresponding OSM tag keys.
address	Optional[dict]	Dictionary of address parts directly attributed to the place. Keys are usually the corresponding OSM tag keys with the addr: prefix removed.
extratags	Optional[dict]	Dictionary of additional attributes for the place. Usually OSM tag keys and values.
housenumber	Optional[str]	House number of the place, normalised for lookup. To get the house number in its original spelling, use address['housenumber'].
postcode	Optional[str]	Computed postcode for the place. To get directly attributed postcodes, use address['postcode'] instead.
wikipedia	Optional[str]	Reference to a wikipedia site for the place. The string has the format :.
rank_address	int	Address rank.
rank_search	int	Search rank.
importance	Optional[float]	Relative importance of the place. This is a measure how likely the place will be searched for.
country_code	Optional[str]	Country the feature is in as ISO 3166-1 alpha-2 country code.
address_rows	Optional[AddressLines]	List of places that make up the computed address. None when address_details parameter was False.
linked_rows	Optional[AddressLines]	List of places that link to the object. None when linked_places parameter was False.
parented_rows	Optional[AddressLines]	List of direct children of the place. None when parented_places parameter was False.
name_keywords	Optional[WordInfos]	List of search words for the name of the place. None when keywords parameter is set to False.
address_keywords	Optional[WordInfos]	List of search word for the address of the place. None when keywords parameter is set to False.
bbox	Bbox	Bounding box of the full geometry of the place. If the place is a single point, then the size of the bounding box is guessed according to the type of place.
geometry	dict	Dictionary containing the full geometry of the place in the formats requested in the geometry_output parameter.

reverse(coord, **params)

Find a place by its coordinates. Also known as reverse geocoding.

Returns the closest result that can be found or None if no place matches the given criteria. The result is a dataclass with the fields as detailed below.

Parameters:

Name	Type	Description	Default
coord	AnyPoint	Coordinate to lookup the place for as a Point or a tuple (x, y). Must be in WGS84 projection.	required

Other Parameters:

Name	Type	Description
max_rank	int	Highest address rank to return. Can be used to restrict search to streets or settlements.
layers	enum	Defines the kind of data to take into account. See description of layers below. (Default: addresses and POIs)
geometry_output	enum	Add the full geometry of the place to the result. Multiple formats may be selected. Note that geometries can become quite large. (Default: none)
geometry_simplification	float	Simplification factor to use on the geometries before returning them. The factor expresses the tolerance in degrees from which the geometry may differ. Topology is preserved. (Default: 0.0)
address_details	bool	Add detailed information about the places that make up the address of the requested object. (Default: False)
linked_places	bool	Add detailed information about the places that link to the result. (Default: False)
parented_places	bool	Add detailed information about all places for which the requested object is a parent, i.e. all places for which the object provides the address details. Only POI places can have parents. (Default: False)
keywords	bool	Add detailed information about the search terms used for this place.

Returns:

Name	Type	Description
source_table	enum	Data source of the place. See below for possible values.
category	tuple	A tuple of two strings with the primary OSM tag and value.
centroid	Point	Point position of the place.
place_id	Optional[int]	Internal ID of the place. This ID may differ for the same place between different installations.
osm_object	Optional[tuple]	OSM type and ID of the place, if available.
names	Optional[dict]	Dictionary of names of the place. Keys are usually the corresponding OSM tag keys.
address	Optional[dict]	Dictionary of address parts directly attributed to the place. Keys are usually the corresponding OSM tag keys with the addr: prefix removed.
extratags	Optional[dict]	Dictionary of additional attributes for the place. Usually OSM tag keys and values.
housenumber	Optional[str]	House number of the place, normalised for lookup. To get the house number in its original spelling, use address['housenumber'].
postcode	Optional[str]	Computed postcode for the place. To get directly attributed postcodes, use address['postcode'] instead.
wikipedia	Optional[str]	Reference to a wikipedia site for the place. The string has the format :.
rank_address	int	Address rank.
rank_search	int	Search rank.
importance	Optional[float]	Relative importance of the place. This is a measure how likely the place will be searched for.
country_code	Optional[str]	Country the feature is in as ISO 3166-1 alpha-2 country code.
address_rows	Optional[AddressLines]	List of places that make up the computed address. None when address_details parameter was False.
linked_rows	Optional[AddressLines]	List of places that link to the object. None when linked_places parameter was False.
parented_rows	Optional[AddressLines]	List of direct children of the place. None when parented_places parameter was False.
name_keywords	Optional[WordInfos]	List of search words for the name of the place. None when keywords parameter is set to False.
address_keywords	Optional[WordInfos]	List of search word for the address of the place. None when keywords parameter is set to False.
bbox	Bbox	Bounding box of the full geometry of the place. If the place is a single point, then the size of the bounding box is guessed according to the type of place.
geometry	dict	Dictionary containing the full geometry of the place in the formats requested in the geometry_output parameter.
distance	Optional[float]	Distance in degree from the input point.

search(query, **params)

Find a place by free-text search. Also known as forward geocoding.

Parameters:

Name	Type	Description	Default
query	str	Free-form text query searching for a place.	required

Other Parameters:

Name	Type	Description
max_results	int	Maximum number of results to return. The actual number of results may be less. (Default: 10)
min_rank	int	Lowest permissible rank for the result. For addressable places this is the minimum address rank. For all other places the search rank is used.
max_rank	int	Highest permissible rank for the result. See min_rank above.
layers	enum	Defines the kind of data to take into account. See layers section for details. (Default: addresses and POIs)
countries	list[str]	Restrict search to countries with the given ISO 3166-1 alpha-2 country code. An empty list (the default) disables this filter.
excluded	list[int]	A list of internal IDs of places to exclude from the search.
viewbox	Optional[Bbox]	Bounding box of an area to focus search on.
bounded_viewbox	bool	Consider the bounding box given in viewbox as a filter and return only results within the bounding box.
near	Optional[Point]	Focus search around the given point and return results ordered by distance to the given point.
near_radius	Optional[float]	Restrict results to results within the given distance in degrees of near point. Ignored, when near is not set.
categories	list[tuple]	Restrict search to places of the given categories. The category is the main OSM tag assigned to each place. An empty list (the default) disables this filter.
geometry_output	enum	Add the full geometry of the place to the result. Multiple formats may be selected. Note that geometries can become quite large. (Default: none)
geometry_simplification	float	Simplification factor to use on the geometries before returning them. The factor expresses the tolerance in degrees from which the geometry may differ. Topology is preserved. (Default: 0.0)
address_details	bool	Add detailed information about the places that make up the address of the requested object. (Default: False)
linked_places	bool	Add detailed information about the places that link to the result. (Default: False)
parented_places	bool	Add detailed information about all places for which the requested object is a parent, i.e. all places for which the object provides the address details. Only POI places can have parents. (Default: False)
keywords	bool	Add detailed information about the search terms used for this place.

Returns:

Name	Type	Description
source_table	enum	Data source of the place. See below for possible values.
category	tuple	A tuple of two strings with the primary OSM tag and value.
centroid	Point	Point position of the place.
place_id	Optional[int]	Internal ID of the place. This ID may differ for the same place between different installations.
osm_object	Optional[tuple]	OSM type and ID of the place, if available.
names	Optional[dict]	Dictionary of names of the place. Keys are usually the corresponding OSM tag keys.
address	Optional[dict]	Dictionary of address parts directly attributed to the place. Keys are usually the corresponding OSM tag keys with the addr: prefix removed.
extratags	Optional[dict]	Dictionary of additional attributes for the place. Usually OSM tag keys and values.
housenumber	Optional[str]	House number of the place, normalised for lookup. To get the house number in its original spelling, use address['housenumber'].
postcode	Optional[str]	Computed postcode for the place. To get directly attributed postcodes, use address['postcode'] instead.
wikipedia	Optional[str]	Reference to a wikipedia site for the place. The string has the format :.
rank_address	int	Address rank.
rank_search	int	Search rank.
importance	Optional[float]	Relative importance of the place. This is a measure how likely the place will be searched for.
country_code	Optional[str]	Country the feature is in as ISO 3166-1 alpha-2 country code.
address_rows	Optional[AddressLines]	List of places that make up the computed address. None when address_details parameter was False.
linked_rows	Optional[AddressLines]	List of places that link to the object. None when linked_places parameter was False.
parented_rows	Optional[AddressLines]	List of direct children of the place. None when parented_places parameter was False.
name_keywords	Optional[WordInfos]	List of search words for the name of the place. None when keywords parameter is set to False.
address_keywords	Optional[WordInfos]	List of search word for the address of the place. None when keywords parameter is set to False.
bbox	Bbox	Bounding box of the full geometry of the place. If the place is a single point, then the size of the bounding box is guessed according to the type of place.
geometry	dict	Dictionary containing the full geometry of the place in the formats requested in the geometry_output parameter.

search_address(amenity=None, street=None, city=None, county=None, state=None, country=None, postalcode=None, **params)

Find an address using structured search.

Parameters:

Name	Type	Description	Default
amenity	Optional[str]	Name of a POI.	None
street	Optional[str]	Street and optionally housenumber of the address. If the address does not have a street, then the place the housenumber references to.	None
city	Optional[str]	Postal city of the address.	None
county	Optional[str]	County equivalent of the address. Does not exist in all jurisdictions.	None
state	Optional[str]	State or province of the address.	None
country	Optional[str]	Country with its full name or its ISO 3166-1 alpha-2 country code. Do not use together with the country_code filter.	None
postalcode	Optional[str]	Post code or ZIP for the place.	None

Other Parameters:

Name	Type	Description
max_results	int	Maximum number of results to return. The actual number of results may be less. (Default: 10)
min_rank	int	Lowest permissible rank for the result. For addressable places this is the minimum address rank. For all other places the search rank is used.
max_rank	int	Highest permissible rank for the result. See min_rank above.
layers	enum	Defines the kind of data to take into account. See layers section for details. (Default: addresses and POIs)
countries	list[str]	Restrict search to countries with the given ISO 3166-1 alpha-2 country code. An empty list (the default) disables this filter. Do not use, when the country parameter is used.
excluded	list[int]	A list of internal IDs of places to exclude from the search.
viewbox	Optional[Bbox]	Bounding box of an area to focus search on.
bounded_viewbox	bool	Consider the bounding box given in viewbox as a filter and return only results within the bounding box.
near	Optional[Point]	Focus search around the given point and return results ordered by distance to the given point.
near_radius	Optional[float]	Restrict results to results within the given distance in degrees of near point. Ignored, when near is not set.
categories	list[tuple]	Restrict search to places of the given categories. The category is the main OSM tag assigned to each place. An empty list (the default) disables this filter.
geometry_output	enum	Add the full geometry of the place to the result. Multiple formats may be selected. Note that geometries can become quite large. (Default: none)
geometry_simplification	float	Simplification factor to use on the geometries before returning them. The factor expresses the tolerance in degrees from which the geometry may differ. Topology is preserved. (Default: 0.0)
address_details	bool	Add detailed information about the places that make up the address of the requested object. (Default: False)
linked_places	bool	Add detailed information about the places that link to the result. (Default: False)
parented_places	bool	Add detailed information about all places for which the requested object is a parent, i.e. all places for which the object provides the address details. Only POI places can have parents. (Default: False)
keywords	bool	Add detailed information about the search terms used for this place.

Returns:

Name	Type	Description
source_table	enum	Data source of the place. See below for possible values.
category	tuple	A tuple of two strings with the primary OSM tag and value.
centroid	Point	Point position of the place.
place_id	Optional[int]	Internal ID of the place. This ID may differ for the same place between different installations.
osm_object	Optional[tuple]	OSM type and ID of the place, if available.
names	Optional[dict]	Dictionary of names of the place. Keys are usually the corresponding OSM tag keys.
address	Optional[dict]	Dictionary of address parts directly attributed to the place. Keys are usually the corresponding OSM tag keys with the addr: prefix removed.
extratags	Optional[dict]	Dictionary of additional attributes for the place. Usually OSM tag keys and values.
housenumber	Optional[str]	House number of the place, normalised for lookup. To get the house number in its original spelling, use address['housenumber'].
postcode	Optional[str]	Computed postcode for the place. To get directly attributed postcodes, use address['postcode'] instead.
wikipedia	Optional[str]	Reference to a wikipedia site for the place. The string has the format :.
rank_address	int	Address rank.
rank_search	int	Search rank.
importance	Optional[float]	Relative importance of the place. This is a measure how likely the place will be searched for.
country_code	Optional[str]	Country the feature is in as ISO 3166-1 alpha-2 country code.
address_rows	Optional[AddressLines]	List of places that make up the computed address. None when address_details parameter was False.
linked_rows	Optional[AddressLines]	List of places that link to the object. None when linked_places parameter was False.
parented_rows	Optional[AddressLines]	List of direct children of the place. None when parented_places parameter was False.
name_keywords	Optional[WordInfos]	List of search words for the name of the place. None when keywords parameter is set to False.
address_keywords	Optional[WordInfos]	List of search word for the address of the place. None when keywords parameter is set to False.
bbox	Bbox	Bounding box of the full geometry of the place. If the place is a single point, then the size of the bounding box is guessed according to the type of place.
geometry	dict	Dictionary containing the full geometry of the place in the formats requested in the geometry_output parameter.

search_category(categories, near_query=None, **params)

Find an object of a certain category near another place.

The near place may either be given as an unstructured search query in itself or as a geographic area through the viewbox or near parameters.

Parameters:

Name	Type	Description	Default
categories	List[Tuple[str, str]]	Restrict search to places of the given categories. The category is the main OSM tag assigned to each place.	required
near_query	Optional[str]	Optional free-text query to define the are to restrict search to.	None

Other Parameters:

Name	Type	Description
max_results	int	Maximum number of results to return. The actual number of results may be less. (Default: 10)
min_rank	int	Lowest permissible rank for the result. For addressable places this is the minimum address rank. For all other places the search rank is used.
max_rank	int	Highest permissible rank for the result. See min_rank above.
layers	enum	Defines the kind of data to take into account. See layers section for details. (Default: addresses and POIs)
countries	list[str]	Restrict search to countries with the given ISO 3166-1 alpha-2 country code. An empty list (the default) disables this filter.
excluded	list[int]	A list of internal IDs of places to exclude from the search.
viewbox	Optional[Bbox]	Bounding box of an area to focus search on.
bounded_viewbox	bool	Consider the bounding box given in viewbox as a filter and return only results within the bounding box.
near	Optional[Point]	Focus search around the given point and return results ordered by distance to the given point.
near_radius	Optional[float]	Restrict results to results within the given distance in degrees of near point. Ignored, when near is not set.
geometry_output	enum	Add the full geometry of the place to the result. Multiple formats may be selected. Note that geometries can become quite large. (Default: none)
geometry_simplification	float	Simplification factor to use on the geometries before returning them. The factor expresses the tolerance in degrees from which the geometry may differ. Topology is preserved. (Default: 0.0)
address_details	bool	Add detailed information about the places that make up the address of the requested object. (Default: False)
linked_places	bool	Add detailed information about the places that link to the result. (Default: False)
parented_places	bool	Add detailed information about all places for which the requested object is a parent, i.e. all places for which the object provides the address details. Only POI places can have parents. (Default: False)
keywords	bool	Add detailed information about the search terms used for this place.

Returns:

Name	Type	Description
source_table	enum	Data source of the place. See below for possible values.
category	tuple	A tuple of two strings with the primary OSM tag and value.
centroid	Point	Point position of the place.
place_id	Optional[int]	Internal ID of the place. This ID may differ for the same place between different installations.
osm_object	Optional[tuple]	OSM type and ID of the place, if available.
names	Optional[dict]	Dictionary of names of the place. Keys are usually the corresponding OSM tag keys.
address	Optional[dict]	Dictionary of address parts directly attributed to the place. Keys are usually the corresponding OSM tag keys with the addr: prefix removed.
extratags	Optional[dict]	Dictionary of additional attributes for the place. Usually OSM tag keys and values.
housenumber	Optional[str]	House number of the place, normalised for lookup. To get the house number in its original spelling, use address['housenumber'].
postcode	Optional[str]	Computed postcode for the place. To get directly attributed postcodes, use address['postcode'] instead.
wikipedia	Optional[str]	Reference to a wikipedia site for the place. The string has the format :.
rank_address	int	Address rank.
rank_search	int	Search rank.
importance	Optional[float]	Relative importance of the place. This is a measure how likely the place will be searched for.
country_code	Optional[str]	Country the feature is in as ISO 3166-1 alpha-2 country code.
address_rows	Optional[AddressLines]	List of places that make up the computed address. None when address_details parameter was False.
linked_rows	Optional[AddressLines]	List of places that link to the object. None when linked_places parameter was False.
parented_rows	Optional[AddressLines]	List of direct children of the place. None when parented_places parameter was False.
name_keywords	Optional[WordInfos]	List of search words for the name of the place. None when keywords parameter is set to False.
address_keywords	Optional[WordInfos]	List of search word for the address of the place. None when keywords parameter is set to False.
bbox	Bbox	Bounding box of the full geometry of the place. If the place is a single point, then the size of the bounding box is guessed according to the type of place.
geometry	dict	Dictionary containing the full geometry of the place in the formats requested in the geometry_output parameter.

NominatimAPIAsync

The main frontend to the Nominatim database implements the functions for lookup, forward and reverse geocoding using asynchronous functions.

This class shares most of the functions with its synchronous version. There are some additional functions or parameters, which are documented below.

This class should usually be used as a context manager in 'with' context.

__init__(project_dir=None, environ=None, loop=None)

Initiate a new frontend object with synchronous API functions.

Parameters:

Name	Type	Description	Default
project_dir	Optional[Union[str, Path]]	Path to the project directory of the local Nominatim installation.	None
environ	Optional[Mapping[str, str]]	Mapping of configuration parameters. When set, replaces any configuration via environment variables. Settings in this mapping also have precedence over any parameters found in the .env file of the project directory.	None
loop	Optional[asyncio.AbstractEventLoop]	The asyncio event loop that will be used when calling functions. Only needed, when a custom event loop is used and the Python version is 3.9 or earlier.	None

setup_database() async

Set up the SQL engine and connections.

This function will be implicitly called when the database is accessed for the first time. You may also call it explicitly to avoid that the first call is delayed by the setup.

close() async

Close all active connections to the database. The NominatimAPIAsync object remains usable after closing. If a new API functions is called, new connections are created.

begin() async

Create a new connection with automatic transaction handling.

This function may be used to get low-level access to the database. Refer to the documentation of SQLAlchemy for details how to use the connection object.