from nominatim.api.results import DetailedResult, ReverseResult, SearchResults
-class NominatimAPIAsync:
- """ API loader asynchornous version.
+class NominatimAPIAsync: #pylint: disable=too-many-instance-attributes
+ """ 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.
"""
def __init__(self, project_dir: Path,
environ: Optional[Mapping[str, str]] = None,
loop: Optional[asyncio.AbstractEventLoop] = None) -> None:
+ """ Initiate a new frontend object with synchronous API functions.
+
+ Parameters:
+ project_dir: Path to the
+ [project directory](../admin/Import.md#creating-the-project-directory)
+ of the local Nominatim installation.
+ environ: Mapping of [configuration parameters](../customize/Settings.md).
+ 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.
+ loop: 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.
+ """
self.config = Configuration(project_dir, environ)
self.query_timeout = self.config.get_int('QUERY_TIMEOUT') \
if self.config.QUERY_TIMEOUT else None
+ self.reverse_restrict_to_country_area = self.config.get_bool('SEARCH_WITHIN_COUNTRIES')
self.server_version = 0
if sys.version_info >= (3, 10):
async def setup_database(self) -> None:
- """ Set up the engine and connection parameters.
+ """ 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
conn.set_query_timeout(self.query_timeout)
if details.keywords:
await make_query_analyzer(conn)
- geocoder = ReverseGeocoder(conn, details)
+ geocoder = ReverseGeocoder(conn, details,
+ self.reverse_restrict_to_country_area)
return await geocoder.lookup(coord)
class NominatimAPI:
- """ API loader, synchronous version.
+ """ 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.
"""
def __init__(self, project_dir: Path,
environ: Optional[Mapping[str, str]] = None) -> None:
+ """ Initiate a new frontend object with synchronous API functions.
+
+ Parameters:
+ project_dir: Path to the
+ [project directory](../admin/Import.md#creating-the-project-directory)
+ of the local Nominatim installation.
+ environ: Mapping of [configuration parameters](../customize/Settings.md).
+ 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.
+ """
self._loop = asyncio.new_event_loop()
self._async_api = NominatimAPIAsync(project_dir, environ, loop=self._loop)
def close(self) -> None:
- """ 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.
+ """ Close all active connections to the database.
+
+ This function also closes the asynchronous worker loop making
+ the NominatimAPI object unusuable.
"""
self._loop.run_until_complete(self._async_api.close())
self._loop.close()
@property
def config(self) -> Configuration:
- """ Return the configuration used by the API.
+ """ Provide read-only access to the [configuration](#Configuration)
+ used by the API.
"""
return self._async_api.config
def status(self) -> StatusResult:
- """ Return the status of the database.
+ """ Return the status of the database as a dataclass object
+ with the fields described below.
+
+ Returns:
+ 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.
"""
return self._loop.run_until_complete(self._async_api.status())
def details(self, place: ntyp.PlaceRef, **params: Any) -> Optional[DetailedResult]:
""" 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:
+ 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:
+ 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:
+ 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 <language code>:<wikipedia title>.
+ rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
+ rank_search (int): [Search rank](../customize/Ranking.md#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.
"""
return self._loop.run_until_complete(self._async_api.details(place, **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:
+ 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:
+ 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:
+ 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 <language code>:<wikipedia title>.
+ rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
+ rank_search (int): [Search rank](../customize/Ranking.md#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.
"""
return self._loop.run_until_complete(self._async_api.lookup(places, **params))
def reverse(self, coord: ntyp.AnyPoint, **params: Any) -> Optional[ReverseResult]:
""" 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.
+ 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:
+ coord: Coordinate to lookup the place for as a Point
+ or a tuple (x, y). Must be in WGS84 projection.
+
+ Other parameters:
+ 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:
+ 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 <language code>:<wikipedia title>.
+ rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
+ rank_search (int): [Search rank](../customize/Ranking.md#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.
"""
return self._loop.run_until_complete(self._async_api.reverse(coord, **params))
def search(self, query: str, **params: Any) -> SearchResults:
""" Find a place by free-text search. Also known as forward geocoding.
+
+ Parameters:
+ query: Free-form text query searching for a place.
+
+ Other parameters:
+ 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](../customize/Ranking.md#address-rank). For all
+ other places the [search rank](../customize/Ranking.md#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](Input-Parameter-Types.md#layers) 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:
+ 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 <language code>:<wikipedia title>.
+ rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
+ rank_search (int): [Search rank](../customize/Ranking.md#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.
"""
return self._loop.run_until_complete(
self._async_api.search(query, **params))
postalcode: Optional[str] = None,
**params: Any) -> SearchResults:
""" Find an address using structured search.
+
+ Parameters:
+ amenity: Name of a POI.
+ street: Street and optionally housenumber of the address. If the address
+ does not have a street, then the place the housenumber references to.
+ city: Postal city of the address.
+ county: County equivalent of the address. Does not exist in all
+ jurisdictions.
+ state: State or province of the address.
+ country: Country with its full name or its ISO 3166-1 alpha-2 country code.
+ Do not use together with the country_code filter.
+ postalcode: Post code or ZIP for the place.
+
+ Other parameters:
+ 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](../customize/Ranking.md#address-rank). For all
+ other places the [search rank](../customize/Ranking.md#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](Input-Parameter-Types.md#layers) 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:
+ 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 <language code>:<wikipedia title>.
+ rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
+ rank_search (int): [Search rank](../customize/Ranking.md#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.
"""
return self._loop.run_until_complete(
self._async_api.search_address(amenity, street, city, county,
near_query: Optional[str] = None,
**params: Any) -> SearchResults:
""" 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:
+ categories: Restrict search to places of the given
+ categories. The category is the main OSM tag assigned to each
+ place.
+ near_query: Optional free-text query to define the are to
+ restrict search to.
+
+ Other parameters:
+ 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](../customize/Ranking.md#address-rank). For all
+ other places the [search rank](../customize/Ranking.md#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](Input-Parameter-Types.md#layers) 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:
+ 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 <language code>:<wikipedia title>.
+ rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
+ rank_search (int): [Search rank](../customize/Ranking.md#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.
"""
return self._loop.run_until_complete(
self._async_api.search_category(categories, near_query, **params))
projects / nominatim.git / blobdiff