X-Git-Url: https://git.openstreetmap.org/nominatim.git/blobdiff_plain/b529e054cf682ad53d16234752df9bbcc85cd396..HEAD:/nominatim/api/core.py diff --git a/nominatim/api/core.py b/nominatim/api/core.py deleted file mode 100644 index a6b49404..00000000 --- a/nominatim/api/core.py +++ /dev/null @@ -1,936 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-only -# -# This file is part of Nominatim. (https://nominatim.org) -# -# Copyright (C) 2023 by the Nominatim developer community. -# For a full list of authors see the git log. -""" -Implementation of classes for API access via libraries. -""" -from typing import Mapping, Optional, Any, AsyncIterator, Dict, Sequence, List, Tuple -import asyncio -import sys -import contextlib -from pathlib import Path - -import sqlalchemy as sa -import sqlalchemy.ext.asyncio as sa_asyncio - -from nominatim.errors import UsageError -from nominatim.db.sqlalchemy_schema import SearchTables -from nominatim.db.async_core_library import PGCORE_LIB, PGCORE_ERROR -from nominatim.config import Configuration -from nominatim.api.connection import SearchConnection -from nominatim.api.status import get_status, StatusResult -from nominatim.api.lookup import get_detailed_place, get_simple_place -from nominatim.api.reverse import ReverseGeocoder -from nominatim.api.search import ForwardGeocoder, Phrase, PhraseType, make_query_analyzer -import nominatim.api.types as ntyp -from nominatim.api.results import DetailedResult, ReverseResult, SearchResults - - -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): - self._engine_lock = asyncio.Lock() - else: - self._engine_lock = asyncio.Lock(loop=loop) # pylint: disable=unexpected-keyword-arg - self._engine: Optional[sa_asyncio.AsyncEngine] = None - self._tables: Optional[SearchTables] = None - self._property_cache: Dict[str, Any] = {'DB:server_version': 0} - - - async def setup_database(self) -> None: - """ 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. - """ - async with self._engine_lock: - if self._engine: - return - - dsn = self.config.get_database_params() - pool_size = self.config.get_int('API_POOL_SIZE') - - query = {k: v for k, v in dsn.items() - if k not in ('user', 'password', 'dbname', 'host', 'port')} - - dburl = sa.engine.URL.create( - f'postgresql+{PGCORE_LIB}', - database=dsn.get('dbname'), - username=dsn.get('user'), password=dsn.get('password'), - host=dsn.get('host'), port=int(dsn['port']) if 'port' in dsn else None, - query=query) - engine = sa_asyncio.create_async_engine(dburl, future=True, - max_overflow=0, pool_size=pool_size, - echo=self.config.get_bool('DEBUG_SQL')) - - try: - async with engine.begin() as conn: - result = await conn.scalar(sa.text('SHOW server_version_num')) - server_version = int(result) - except (PGCORE_ERROR, sa.exc.OperationalError): - server_version = 0 - - if server_version >= 110000: - @sa.event.listens_for(engine.sync_engine, "connect") - def _on_connect(dbapi_con: Any, _: Any) -> None: - cursor = dbapi_con.cursor() - cursor.execute("SET jit_above_cost TO '-1'") - cursor.execute("SET max_parallel_workers_per_gather TO '0'") - # Make sure that all connections get the new settings - await self.close() - - self._property_cache['DB:server_version'] = server_version - - self._tables = SearchTables(sa.MetaData(), engine.name) # pylint: disable=no-member - self._engine = engine - - - async 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. - """ - if self._engine is not None: - await self._engine.dispose() - - - @contextlib.asynccontextmanager - async def begin(self) -> AsyncIterator[SearchConnection]: - """ 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. - """ - if self._engine is None: - await self.setup_database() - - assert self._engine is not None - assert self._tables is not None - - async with self._engine.begin() as conn: - yield SearchConnection(conn, self._tables, self._property_cache) - - - async def status(self) -> StatusResult: - """ Return the status of the database. - """ - try: - async with self.begin() as conn: - conn.set_query_timeout(self.query_timeout) - status = await get_status(conn) - except (PGCORE_ERROR, sa.exc.OperationalError): - return StatusResult(700, 'Database connection failed') - - return status - - - async def details(self, place: ntyp.PlaceRef, **params: Any) -> Optional[DetailedResult]: - """ Get detailed information about a place in the database. - - Returns None if there is no entry under the given ID. - """ - details = ntyp.LookupDetails.from_kwargs(params) - async with self.begin() as conn: - conn.set_query_timeout(self.query_timeout) - if details.keywords: - await make_query_analyzer(conn) - return await get_detailed_place(conn, place, details) - - - async def lookup(self, places: Sequence[ntyp.PlaceRef], **params: Any) -> SearchResults: - """ Get simple information about a list of places. - - Returns a list of place information for all IDs that were found. - """ - details = ntyp.LookupDetails.from_kwargs(params) - async with self.begin() as conn: - conn.set_query_timeout(self.query_timeout) - if details.keywords: - await make_query_analyzer(conn) - return SearchResults(filter(None, - [await get_simple_place(conn, p, details) for p in places])) - - - async 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. - """ - # The following negation handles NaN correctly. Don't change. - if not abs(coord[0]) <= 180 or not abs(coord[1]) <= 90: - # There are no results to be expected outside valid coordinates. - return None - - details = ntyp.ReverseDetails.from_kwargs(params) - async with self.begin() as conn: - conn.set_query_timeout(self.query_timeout) - if details.keywords: - await make_query_analyzer(conn) - geocoder = ReverseGeocoder(conn, details, - self.reverse_restrict_to_country_area) - return await geocoder.lookup(coord) - - - async def search(self, query: str, **params: Any) -> SearchResults: - """ Find a place by free-text search. Also known as forward geocoding. - """ - query = query.strip() - if not query: - raise UsageError('Nothing to search for.') - - async with self.begin() as conn: - conn.set_query_timeout(self.query_timeout) - geocoder = ForwardGeocoder(conn, ntyp.SearchDetails.from_kwargs(params), - self.config.get_int('REQUEST_TIMEOUT') \ - if self.config.REQUEST_TIMEOUT else None) - phrases = [Phrase(PhraseType.NONE, p.strip()) for p in query.split(',')] - return await geocoder.lookup(phrases) - - - # pylint: disable=too-many-arguments,too-many-branches - async def search_address(self, amenity: Optional[str] = None, - street: Optional[str] = None, - city: Optional[str] = None, - county: Optional[str] = None, - state: Optional[str] = None, - country: Optional[str] = None, - postalcode: Optional[str] = None, - **params: Any) -> SearchResults: - """ Find an address using structured search. - """ - async with self.begin() as conn: - conn.set_query_timeout(self.query_timeout) - details = ntyp.SearchDetails.from_kwargs(params) - - phrases: List[Phrase] = [] - - if amenity: - phrases.append(Phrase(PhraseType.AMENITY, amenity)) - if street: - phrases.append(Phrase(PhraseType.STREET, street)) - if city: - phrases.append(Phrase(PhraseType.CITY, city)) - if county: - phrases.append(Phrase(PhraseType.COUNTY, county)) - if state: - phrases.append(Phrase(PhraseType.STATE, state)) - if postalcode: - phrases.append(Phrase(PhraseType.POSTCODE, postalcode)) - if country: - phrases.append(Phrase(PhraseType.COUNTRY, country)) - - if not phrases: - raise UsageError('Nothing to search for.') - - if amenity or street: - details.restrict_min_max_rank(26, 30) - elif city: - details.restrict_min_max_rank(13, 25) - elif county: - details.restrict_min_max_rank(10, 12) - elif state: - details.restrict_min_max_rank(5, 9) - elif postalcode: - details.restrict_min_max_rank(5, 11) - else: - details.restrict_min_max_rank(4, 4) - - if 'layers' not in params: - details.layers = ntyp.DataLayer.ADDRESS - if amenity: - details.layers |= ntyp.DataLayer.POI - - geocoder = ForwardGeocoder(conn, details, - self.config.get_int('REQUEST_TIMEOUT') \ - if self.config.REQUEST_TIMEOUT else None) - return await geocoder.lookup(phrases) - - - async def search_category(self, categories: List[Tuple[str, str]], - 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 coordinates. - """ - if not categories: - return SearchResults() - - details = ntyp.SearchDetails.from_kwargs(params) - async with self.begin() as conn: - conn.set_query_timeout(self.query_timeout) - if near_query: - phrases = [Phrase(PhraseType.NONE, p) for p in near_query.split(',')] - else: - phrases = [] - if details.keywords: - await make_query_analyzer(conn) - - geocoder = ForwardGeocoder(conn, details, - self.config.get_int('REQUEST_TIMEOUT') \ - if self.config.REQUEST_TIMEOUT else None) - return await geocoder.lookup_pois(categories, phrases) - - - -class 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. - """ - - 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. - - 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: - """ 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 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 :. - 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)) - - - def lookup(self, places: Sequence[ntyp.PlaceRef], **params: Any) -> SearchResults: - """ 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 :. - 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. 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 :. - 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 :. - 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)) - - - # pylint: disable=too-many-arguments - def search_address(self, amenity: Optional[str] = None, - street: Optional[str] = None, - city: Optional[str] = None, - county: Optional[str] = None, - state: Optional[str] = None, - country: Optional[str] = None, - 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 :. - 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, - state, country, postalcode, **params)) - - - def search_category(self, categories: List[Tuple[str, str]], - 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 :. - 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))