X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/36d068871da6921f6f2a7cd81df393f4fa3661a9..558c42ec83a5a01e238af2fa4faa6a992af3f77a:/nominatim/api/core.py diff --git a/nominatim/api/core.py b/nominatim/api/core.py index 6d47d332..fb03d2df 100644 --- a/nominatim/api/core.py +++ b/nominatim/api/core.py @@ -7,41 +7,70 @@ """ Implementation of classes for API access via libraries. """ -from typing import Mapping, Optional, Any, AsyncIterator, Dict +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 -import asyncpg +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_place_by_id +from nominatim.api.lookup import get_detailed_place, get_simple_place from nominatim.api.reverse import ReverseGeocoder -from nominatim.api.types import PlaceRef, LookupDetails, AnyPoint, DataLayer -from nominatim.api.results import DetailedResult, ReverseResult +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: - """ API loader asynchornous version. + """ 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) -> None: + 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.server_version = 0 - self._engine_lock = asyncio.Lock() + 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 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 @@ -52,29 +81,26 @@ class NominatimAPIAsync: 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')} - query['prepared_statement_cache_size'] = '0' dburl = sa.engine.URL.create( - 'postgresql+asyncpg', + 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, - connect_args={'server_settings': { - 'DateStyle': 'sql,european', - 'max_parallel_workers_per_gather': '0' - }}) + 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 asyncpg.PostgresError: + except (PGCORE_ERROR, sa.exc.OperationalError): server_version = 0 if server_version >= 110000: @@ -82,6 +108,7 @@ class NominatimAPIAsync: 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() @@ -123,26 +150,42 @@ class NominatimAPIAsync: """ try: async with self.begin() as conn: + conn.set_query_timeout(self.query_timeout) status = await get_status(conn) - except asyncpg.PostgresError: + except (PGCORE_ERROR, sa.exc.OperationalError): return StatusResult(700, 'Database connection failed') return status - async def lookup(self, place: PlaceRef, - details: Optional[LookupDetails] = None) -> Optional[DetailedResult]: + 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: - return await get_place_by_id(conn, place, details or LookupDetails()) + 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 reverse(self, coord: AnyPoint, max_rank: Optional[int] = None, - layer: Optional[DataLayer] = None, - details: Optional[LookupDetails] = None) -> Optional[ReverseResult]: + 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 @@ -153,31 +196,145 @@ class NominatimAPIAsync: # There are no results to be expected outside valid coordinates. return None - if layer is None: - layer = DataLayer.ADDRESS | DataLayer.POI + 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) + return await geocoder.lookup(coord) + - max_rank = max(0, min(max_rank or 30, 30)) + 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: - geocoder = ReverseGeocoder(conn, max_rank, layer, - details or LookupDetails()) - return await geocoder.lookup(coord) + 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: - """ 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) + 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() @@ -185,30 +342,576 @@ class NominatimAPI: @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 lookup(self, place: PlaceRef, - details: Optional[LookupDetails] = None) -> Optional[DetailedResult]: + 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 PlaceRef below + 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.lookup(place, details)) + 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 PlaceRef below + 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: AnyPoint, max_rank: Optional[int] = None, - layer: Optional[DataLayer] = None, - details: Optional[LookupDetails] = None) -> Optional[ReverseResult]: + 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 :. + 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 [address rank](../customize/Ranking.md#address-rank) to return. + max_rank (int): Highest address rank to return. + layers (enum): Defines the kind of data to take into account. + See description of layers below. (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 [address rank](../customize/Ranking.md#address-rank) to return. + max_rank (int): Highest address rank to return. + layers (enum): Defines the kind of data to take into account. + See description of layers below. (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 [address rank](../customize/Ranking.md#address-rank) to return. + max_rank (int): Highest address rank to return. + layers (enum): Defines the kind of data to take into account. + See description of layers below. (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.reverse(coord, max_rank, layer, details)) + self._async_api.search_category(categories, near_query, **params))