Skip to content

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.

__init__(project_dir, environ=None)

Initiate a new frontend object with synchronous API functions.

Parameters:

Name Type Description Default
project_dir Path

Path to the project directory of the local Nominatim installation.

required
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 unusuable.

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 linkes 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
rank_search int
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[nominatim.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
rank_search int
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
rank_search int
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
rank_search int
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
rank_search int
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
rank_search int
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.

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

Initiate a new frontend object with synchronous API functions.

Parameters:

Name Type Description Default
project_dir Path

Path to the project directory of the local Nominatim installation.

required
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.