nominatim/api/core.py

   1 # SPDX-License-Identifier: GPL-2.0-only
   2 #
   3 # This file is part of Nominatim. (https://nominatim.org)
   4 #
   5 # Copyright (C) 2023 by the Nominatim developer community.
   6 # For a full list of authors see the git log.
   7 """
   8 Implementation of classes for API access via libraries.
   9 """
  10 from typing import Mapping, Optional, Any, AsyncIterator, Dict, Sequence, List, Tuple
  11 import asyncio
  12 import sys
  13 import contextlib
  14 from pathlib import Path
  15
  16 import sqlalchemy as sa
  17 import sqlalchemy.ext.asyncio as sa_asyncio
  18
  19 from nominatim.errors import UsageError
  20 from nominatim.db.sqlalchemy_schema import SearchTables
  21 from nominatim.db.async_core_library import PGCORE_LIB, PGCORE_ERROR
  22 from nominatim.config import Configuration
  23 from nominatim.api.connection import SearchConnection
  24 from nominatim.api.status import get_status, StatusResult
  25 from nominatim.api.lookup import get_detailed_place, get_simple_place
  26 from nominatim.api.reverse import ReverseGeocoder
  27 from nominatim.api.search import ForwardGeocoder, Phrase, PhraseType, make_query_analyzer
  28 import nominatim.api.types as ntyp
  29 from nominatim.api.results import DetailedResult, ReverseResult, SearchResults
  30
  31
  32 class NominatimAPIAsync: #pylint: disable=too-many-instance-attributes
  33     """ The main frontend to the Nominatim database implements the
  34         functions for lookup, forward and reverse geocoding using
  35         asynchronous functions.
  36
  37         This class shares most of the functions with its synchronous
  38         version. There are some additional functions or parameters,
  39         which are documented below.
  40     """
  41     def __init__(self, project_dir: Path,
  42                  environ: Optional[Mapping[str, str]] = None,
  43                  loop: Optional[asyncio.AbstractEventLoop] = None) -> None:
  44         """ Initiate a new frontend object with synchronous API functions.
  45
  46             Parameters:
  47               project_dir: Path to the
  48                   [project directory](../admin/Import.md#creating-the-project-directory)
  49                   of the local Nominatim installation.
  50               environ: Mapping of [configuration parameters](../customize/Settings.md).
  51                   When set, replaces any configuration via environment variables.
  52                   Settings in this mapping also have precedence over any
  53                   parameters found in the `.env` file of the project directory.
  54               loop: The asyncio event loop that will be used when calling
  55                   functions. Only needed, when a custom event loop is used
  56                   and the Python version is 3.9 or earlier.
  57         """
  58         self.config = Configuration(project_dir, environ)
  59         self.query_timeout = self.config.get_int('QUERY_TIMEOUT') \
  60                              if self.config.QUERY_TIMEOUT else None
  61         self.reverse_restrict_to_country_area = self.config.get_bool('SEARCH_WITHIN_COUNTRIES')
  62         self.server_version = 0
  63
  64         if sys.version_info >= (3, 10):
  65             self._engine_lock = asyncio.Lock()
  66         else:
  67             self._engine_lock = asyncio.Lock(loop=loop) # pylint: disable=unexpected-keyword-arg
  68         self._engine: Optional[sa_asyncio.AsyncEngine] = None
  69         self._tables: Optional[SearchTables] = None
  70         self._property_cache: Dict[str, Any] = {'DB:server_version': 0}
  71
  72
  73     async def setup_database(self) -> None:
  74         """ Set up the SQL engine and connections.
  75
  76             This function will be implicitly called when the database is
  77             accessed for the first time. You may also call it explicitly to
  78             avoid that the first call is delayed by the setup.
  79         """
  80         async with self._engine_lock:
  81             if self._engine:
  82                 return
  83
  84             dsn = self.config.get_database_params()
  85             pool_size = self.config.get_int('API_POOL_SIZE')
  86
  87             query = {k: v for k, v in dsn.items()
  88                       if k not in ('user', 'password', 'dbname', 'host', 'port')}
  89
  90             dburl = sa.engine.URL.create(
  91                        f'postgresql+{PGCORE_LIB}',
  92                        database=dsn.get('dbname'),
  93                        username=dsn.get('user'), password=dsn.get('password'),
  94                        host=dsn.get('host'), port=int(dsn['port']) if 'port' in dsn else None,
  95                        query=query)
  96             engine = sa_asyncio.create_async_engine(dburl, future=True,
  97                                                     max_overflow=0, pool_size=pool_size,
  98                                                     echo=self.config.get_bool('DEBUG_SQL'))
  99
 100             try:
 101                 async with engine.begin() as conn:
 102                     result = await conn.scalar(sa.text('SHOW server_version_num'))
 103                     server_version = int(result)
 104             except (PGCORE_ERROR, sa.exc.OperationalError):
 105                 server_version = 0
 106
 107             if server_version >= 110000:
 108                 @sa.event.listens_for(engine.sync_engine, "connect")
 109                 def _on_connect(dbapi_con: Any, _: Any) -> None:
 110                     cursor = dbapi_con.cursor()
 111                     cursor.execute("SET jit_above_cost TO '-1'")
 112                     cursor.execute("SET max_parallel_workers_per_gather TO '0'")
 113                 # Make sure that all connections get the new settings
 114                 await self.close()
 115
 116             self._property_cache['DB:server_version'] = server_version
 117
 118             self._tables = SearchTables(sa.MetaData(), engine.name) # pylint: disable=no-member
 119             self._engine = engine
 120
 121
 122     async def close(self) -> None:
 123         """ Close all active connections to the database. The NominatimAPIAsync
 124             object remains usable after closing. If a new API functions is
 125             called, new connections are created.
 126         """
 127         if self._engine is not None:
 128             await self._engine.dispose()
 129
 130
 131     @contextlib.asynccontextmanager
 132     async def begin(self) -> AsyncIterator[SearchConnection]:
 133         """ Create a new connection with automatic transaction handling.
 134
 135             This function may be used to get low-level access to the database.
 136             Refer to the documentation of SQLAlchemy for details how to use
 137             the connection object.
 138         """
 139         if self._engine is None:
 140             await self.setup_database()
 141
 142         assert self._engine is not None
 143         assert self._tables is not None
 144
 145         async with self._engine.begin() as conn:
 146             yield SearchConnection(conn, self._tables, self._property_cache)
 147
 148
 149     async def status(self) -> StatusResult:
 150         """ Return the status of the database.
 151         """
 152         try:
 153             async with self.begin() as conn:
 154                 conn.set_query_timeout(self.query_timeout)
 155                 status = await get_status(conn)
 156         except (PGCORE_ERROR, sa.exc.OperationalError):
 157             return StatusResult(700, 'Database connection failed')
 158
 159         return status
 160
 161
 162     async def details(self, place: ntyp.PlaceRef, **params: Any) -> Optional[DetailedResult]:
 163         """ Get detailed information about a place in the database.
 164
 165             Returns None if there is no entry under the given ID.
 166         """
 167         details = ntyp.LookupDetails.from_kwargs(params)
 168         async with self.begin() as conn:
 169             conn.set_query_timeout(self.query_timeout)
 170             if details.keywords:
 171                 await make_query_analyzer(conn)
 172             return await get_detailed_place(conn, place, details)
 173
 174
 175     async def lookup(self, places: Sequence[ntyp.PlaceRef], **params: Any) -> SearchResults:
 176         """ Get simple information about a list of places.
 177
 178             Returns a list of place information for all IDs that were found.
 179         """
 180         details = ntyp.LookupDetails.from_kwargs(params)
 181         async with self.begin() as conn:
 182             conn.set_query_timeout(self.query_timeout)
 183             if details.keywords:
 184                 await make_query_analyzer(conn)
 185             return SearchResults(filter(None,
 186                                         [await get_simple_place(conn, p, details) for p in places]))
 187
 188
 189     async def reverse(self, coord: ntyp.AnyPoint, **params: Any) -> Optional[ReverseResult]:
 190         """ Find a place by its coordinates. Also known as reverse geocoding.
 191
 192             Returns the closest result that can be found or None if
 193             no place matches the given criteria.
 194         """
 195         # The following negation handles NaN correctly. Don't change.
 196         if not abs(coord[0]) <= 180 or not abs(coord[1]) <= 90:
 197             # There are no results to be expected outside valid coordinates.
 198             return None
 199
 200         details = ntyp.ReverseDetails.from_kwargs(params)
 201         async with self.begin() as conn:
 202             conn.set_query_timeout(self.query_timeout)
 203             if details.keywords:
 204                 await make_query_analyzer(conn)
 205             geocoder = ReverseGeocoder(conn, details,
 206                                        self.reverse_restrict_to_country_area)
 207             return await geocoder.lookup(coord)
 208
 209
 210     async def search(self, query: str, **params: Any) -> SearchResults:
 211         """ Find a place by free-text search. Also known as forward geocoding.
 212         """
 213         query = query.strip()
 214         if not query:
 215             raise UsageError('Nothing to search for.')
 216
 217         async with self.begin() as conn:
 218             conn.set_query_timeout(self.query_timeout)
 219             geocoder = ForwardGeocoder(conn, ntyp.SearchDetails.from_kwargs(params),
 220                                        self.config.get_int('REQUEST_TIMEOUT') \
 221                                          if self.config.REQUEST_TIMEOUT else None)
 222             phrases = [Phrase(PhraseType.NONE, p.strip()) for p in query.split(',')]
 223             return await geocoder.lookup(phrases)
 224
 225
 226     # pylint: disable=too-many-arguments,too-many-branches
 227     async def search_address(self, amenity: Optional[str] = None,
 228                              street: Optional[str] = None,
 229                              city: Optional[str] = None,
 230                              county: Optional[str] = None,
 231                              state: Optional[str] = None,
 232                              country: Optional[str] = None,
 233                              postalcode: Optional[str] = None,
 234                              **params: Any) -> SearchResults:
 235         """ Find an address using structured search.
 236         """
 237         async with self.begin() as conn:
 238             conn.set_query_timeout(self.query_timeout)
 239             details = ntyp.SearchDetails.from_kwargs(params)
 240
 241             phrases: List[Phrase] = []
 242
 243             if amenity:
 244                 phrases.append(Phrase(PhraseType.AMENITY, amenity))
 245             if street:
 246                 phrases.append(Phrase(PhraseType.STREET, street))
 247             if city:
 248                 phrases.append(Phrase(PhraseType.CITY, city))
 249             if county:
 250                 phrases.append(Phrase(PhraseType.COUNTY, county))
 251             if state:
 252                 phrases.append(Phrase(PhraseType.STATE, state))
 253             if postalcode:
 254                 phrases.append(Phrase(PhraseType.POSTCODE, postalcode))
 255             if country:
 256                 phrases.append(Phrase(PhraseType.COUNTRY, country))
 257
 258             if not phrases:
 259                 raise UsageError('Nothing to search for.')
 260
 261             if amenity or street:
 262                 details.restrict_min_max_rank(26, 30)
 263             elif city:
 264                 details.restrict_min_max_rank(13, 25)
 265             elif county:
 266                 details.restrict_min_max_rank(10, 12)
 267             elif state:
 268                 details.restrict_min_max_rank(5, 9)
 269             elif postalcode:
 270                 details.restrict_min_max_rank(5, 11)
 271             else:
 272                 details.restrict_min_max_rank(4, 4)
 273
 274             if 'layers' not in params:
 275                 details.layers = ntyp.DataLayer.ADDRESS
 276                 if amenity:
 277                     details.layers |= ntyp.DataLayer.POI
 278
 279             geocoder = ForwardGeocoder(conn, details,
 280                                        self.config.get_int('REQUEST_TIMEOUT') \
 281                                          if self.config.REQUEST_TIMEOUT else None)
 282             return await geocoder.lookup(phrases)
 283
 284
 285     async def search_category(self, categories: List[Tuple[str, str]],
 286                               near_query: Optional[str] = None,
 287                               **params: Any) -> SearchResults:
 288         """ Find an object of a certain category near another place.
 289             The near place may either be given as an unstructured search
 290             query in itself or as coordinates.
 291         """
 292         if not categories:
 293             return SearchResults()
 294
 295         details = ntyp.SearchDetails.from_kwargs(params)
 296         async with self.begin() as conn:
 297             conn.set_query_timeout(self.query_timeout)
 298             if near_query:
 299                 phrases = [Phrase(PhraseType.NONE, p) for p in near_query.split(',')]
 300             else:
 301                 phrases = []
 302                 if details.keywords:
 303                     await make_query_analyzer(conn)
 304
 305             geocoder = ForwardGeocoder(conn, details,
 306                                        self.config.get_int('REQUEST_TIMEOUT') \
 307                                          if self.config.REQUEST_TIMEOUT else None)
 308             return await geocoder.lookup_pois(categories, phrases)
 309
 310
 311
 312 class NominatimAPI:
 313     """ This class provides a thin synchronous wrapper around the asynchronous
 314         Nominatim functions. It creates its own event loop and runs each
 315         synchronous function call to completion using that loop.
 316     """
 317
 318     def __init__(self, project_dir: Path,
 319                  environ: Optional[Mapping[str, str]] = None) -> None:
 320         """ Initiate a new frontend object with synchronous API functions.
 321
 322             Parameters:
 323               project_dir: Path to the
 324                   [project directory](../admin/Import.md#creating-the-project-directory)
 325                   of the local Nominatim installation.
 326               environ: Mapping of [configuration parameters](../customize/Settings.md).
 327                   When set, replaces any configuration via environment variables.
 328                   Settings in this mapping also have precedence over any
 329                   parameters found in the `.env` file of the project directory.
 330         """
 331         self._loop = asyncio.new_event_loop()
 332         self._async_api = NominatimAPIAsync(project_dir, environ, loop=self._loop)
 333
 334
 335     def close(self) -> None:
 336         """ Close all active connections to the database.
 337
 338             This function also closes the asynchronous worker loop making
 339             the NominatimAPI object unusuable.
 340         """
 341         self._loop.run_until_complete(self._async_api.close())
 342         self._loop.close()
 343
 344
 345     @property
 346     def config(self) -> Configuration:
 347         """ Provide read-only access to the [configuration](#Configuration)
 348             used by the API.
 349         """
 350         return self._async_api.config
 351
 352     def status(self) -> StatusResult:
 353         """ Return the status of the database as a dataclass object
 354             with the fields described below.
 355
 356             Returns:
 357               status(int): A status code as described on the status page.
 358               message(str): Either 'OK' or a human-readable message of the
 359                   problem encountered.
 360               software_version(tuple): A tuple with the version of the
 361                   Nominatim library consisting of (major, minor, patch, db-patch)
 362                   version.
 363               database_version(tuple): A tuple with the version of the library
 364                   which was used for the import or last migration.
 365                   Also consists of (major, minor, patch, db-patch).
 366               data_updated(datetime): Timestamp with the age of the data.
 367         """
 368         return self._loop.run_until_complete(self._async_api.status())
 369
 370
 371     def details(self, place: ntyp.PlaceRef, **params: Any) -> Optional[DetailedResult]:
 372         """ Get detailed information about a place in the database.
 373
 374             The result is a dataclass object with the fields described below
 375             or `None` if the place could not be found in the database.
 376
 377             Parameters:
 378               place: Description of the place to look up. See
 379                      [Place identification](Input-Parameter-Types.md#place-identification)
 380                      for the various ways to reference a place.
 381
 382             Other parameters:
 383               geometry_output (enum): Add the full geometry of the place to the result.
 384                 Multiple formats may be selected. Note that geometries can become
 385                 quite large. (Default: none)
 386               geometry_simplification (float): Simplification factor to use on
 387                 the geometries before returning them. The factor expresses
 388                 the tolerance in degrees from which the geometry may differ.
 389                 Topology is preserved. (Default: 0.0)
 390               address_details (bool): Add detailed information about the places
 391                 that make up the address of the requested object. (Default: False)
 392               linked_places (bool): Add detailed information about the places
 393                 that link to the result. (Default: False)
 394               parented_places (bool): Add detailed information about all places
 395                 for which the requested object is a parent, i.e. all places for
 396                 which the object provides the address details.
 397                 Only POI places can have parents. (Default: False)
 398               keywords (bool): Add detailed information about the search terms
 399                 used for this place.
 400
 401             Returns:
 402               source_table (enum): Data source of the place. See below for possible values.
 403               category (tuple): A tuple of two strings with the primary OSM tag
 404                   and value.
 405               centroid (Point): Point position of the place.
 406               place_id (Optional[int]): Internal ID of the place. This ID may differ
 407                   for the same place between different installations.
 408               parent_place_id (Optional(int]): Internal ID of the parent of this
 409                   place. Only meaning full for POI-like objects (places with a
 410                   rank_address of 30).
 411               linked_place_id (Optional[int]): Internal ID of the place this object
 412                   linkes to. When this ID is set then there is no guarantee that
 413                   the rest of the result information is complete.
 414               admin_level (int): Value of the `admin_level` OSM tag. Only meaningful
 415                   for administrative boundary objects.
 416               indexed_date (datetime): Timestamp when the place was last updated.
 417               osm_object (Optional[tuple]): OSM type and ID of the place, if available.
 418               names (Optional[dict]): Dictionary of names of the place. Keys are
 419                   usually the corresponding OSM tag keys.
 420               address (Optional[dict]): Dictionary of address parts directly
 421                   attributed to the place. Keys are usually the corresponding
 422                   OSM tag keys with the `addr:` prefix removed.
 423               extratags (Optional[dict]): Dictionary of additional attributes for
 424                   the place. Usually OSM tag keys and values.
 425               housenumber (Optional[str]): House number of the place, normalised
 426                   for lookup. To get the house number in its original spelling,
 427                   use `address['housenumber']`.
 428               postcode (Optional[str]): Computed postcode for the place. To get
 429                   directly attributed postcodes, use `address['postcode']` instead.
 430               wikipedia (Optional[str]): Reference to a wikipedia site for the place.
 431                   The string has the format <language code>:<wikipedia title>.
 432               rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
 433               rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
 434               importance (Optional[float]): Relative importance of the place. This is a measure
 435                   how likely the place will be searched for.
 436               country_code (Optional[str]): Country the feature is in as
 437                   ISO 3166-1 alpha-2 country code.
 438               address_rows (Optional[AddressLines]): List of places that make up the
 439                   computed address. `None` when `address_details` parameter was False.
 440               linked_rows (Optional[AddressLines]): List of places that link to the object.
 441                   `None` when `linked_places` parameter was False.
 442               parented_rows (Optional[AddressLines]): List of direct children of the place.
 443                   `None` when `parented_places` parameter was False.
 444               name_keywords (Optional[WordInfos]): List of search words for the name of
 445                    the place. `None` when `keywords` parameter is set to False.
 446               address_keywords (Optional[WordInfos]): List of search word for the address of
 447                    the place. `None` when `keywords` parameter is set to False.
 448               geometry (dict): Dictionary containing the full geometry of the place
 449                    in the formats requested in the `geometry_output` parameter.
 450         """
 451         return self._loop.run_until_complete(self._async_api.details(place, **params))
 452
 453
 454     def lookup(self, places: Sequence[ntyp.PlaceRef], **params: Any) -> SearchResults:
 455         """ Get simple information about a list of places.
 456
 457             Returns a list of place information for all IDs that were found.
 458             Each result is a dataclass with the fields detailed below.
 459
 460             Parameters:
 461               places: List of descriptions of the place to look up. See
 462                       [Place identification](Input-Parameter-Types.md#place-identification)
 463                       for the various ways to reference a place.
 464
 465             Other parameters:
 466               geometry_output (enum): Add the full geometry of the place to the result.
 467                 Multiple formats may be selected. Note that geometries can become
 468                 quite large. (Default: none)
 469               geometry_simplification (float): Simplification factor to use on
 470                 the geometries before returning them. The factor expresses
 471                 the tolerance in degrees from which the geometry may differ.
 472                 Topology is preserved. (Default: 0.0)
 473               address_details (bool): Add detailed information about the places
 474                 that make up the address of the requested object. (Default: False)
 475               linked_places (bool): Add detailed information about the places
 476                 that link to the result. (Default: False)
 477               parented_places (bool): Add detailed information about all places
 478                 for which the requested object is a parent, i.e. all places for
 479                 which the object provides the address details.
 480                 Only POI places can have parents. (Default: False)
 481               keywords (bool): Add detailed information about the search terms
 482                 used for this place.
 483
 484             Returns:
 485               source_table (enum): Data source of the place. See below for possible values.
 486               category (tuple): A tuple of two strings with the primary OSM tag
 487                   and value.
 488               centroid (Point): Point position of the place.
 489               place_id (Optional[int]): Internal ID of the place. This ID may differ
 490                   for the same place between different installations.
 491               osm_object (Optional[tuple]): OSM type and ID of the place, if available.
 492               names (Optional[dict]): Dictionary of names of the place. Keys are
 493                   usually the corresponding OSM tag keys.
 494               address (Optional[dict]): Dictionary of address parts directly
 495                   attributed to the place. Keys are usually the corresponding
 496                   OSM tag keys with the `addr:` prefix removed.
 497               extratags (Optional[dict]): Dictionary of additional attributes for
 498                   the place. Usually OSM tag keys and values.
 499               housenumber (Optional[str]): House number of the place, normalised
 500                   for lookup. To get the house number in its original spelling,
 501                   use `address['housenumber']`.
 502               postcode (Optional[str]): Computed postcode for the place. To get
 503                   directly attributed postcodes, use `address['postcode']` instead.
 504               wikipedia (Optional[str]): Reference to a wikipedia site for the place.
 505                   The string has the format <language code>:<wikipedia title>.
 506               rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
 507               rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
 508               importance (Optional[float]): Relative importance of the place. This is a measure
 509                   how likely the place will be searched for.
 510               country_code (Optional[str]): Country the feature is in as
 511                   ISO 3166-1 alpha-2 country code.
 512               address_rows (Optional[AddressLines]): List of places that make up the
 513                   computed address. `None` when `address_details` parameter was False.
 514               linked_rows (Optional[AddressLines]): List of places that link to the object.
 515                   `None` when `linked_places` parameter was False.
 516               parented_rows (Optional[AddressLines]): List of direct children of the place.
 517                   `None` when `parented_places` parameter was False.
 518               name_keywords (Optional[WordInfos]): List of search words for the name of
 519                    the place. `None` when `keywords` parameter is set to False.
 520               address_keywords (Optional[WordInfos]): List of search word for the address of
 521                    the place. `None` when `keywords` parameter is set to False.
 522               bbox (Bbox): Bounding box of the full geometry of the place.
 523                    If the place is a single point, then the size of the bounding
 524                    box is guessed according to the type of place.
 525               geometry (dict): Dictionary containing the full geometry of the place
 526                    in the formats requested in the `geometry_output` parameter.
 527         """
 528         return self._loop.run_until_complete(self._async_api.lookup(places, **params))
 529
 530
 531     def reverse(self, coord: ntyp.AnyPoint, **params: Any) -> Optional[ReverseResult]:
 532         """ Find a place by its coordinates. Also known as reverse geocoding.
 533
 534             Returns the closest result that can be found or `None` if
 535             no place matches the given criteria. The result is a dataclass
 536             with the fields as detailed below.
 537
 538             Parameters:
 539               coord: Coordinate to lookup the place for as a Point
 540                      or a tuple (x, y). Must be in WGS84 projection.
 541
 542             Other parameters:
 543               max_rank (int): Highest address rank to return. Can be used to
 544                 restrict search to streets or settlements.
 545               layers (enum): Defines the kind of data to take into account.
 546                 See description of layers below. (Default: addresses and POIs)
 547               geometry_output (enum): Add the full geometry of the place to the result.
 548                 Multiple formats may be selected. Note that geometries can become
 549                 quite large. (Default: none)
 550               geometry_simplification (float): Simplification factor to use on
 551                 the geometries before returning them. The factor expresses
 552                 the tolerance in degrees from which the geometry may differ.
 553                 Topology is preserved. (Default: 0.0)
 554               address_details (bool): Add detailed information about the places
 555                 that make up the address of the requested object. (Default: False)
 556               linked_places (bool): Add detailed information about the places
 557                 that link to the result. (Default: False)
 558               parented_places (bool): Add detailed information about all places
 559                 for which the requested object is a parent, i.e. all places for
 560                 which the object provides the address details.
 561                 Only POI places can have parents. (Default: False)
 562               keywords (bool): Add detailed information about the search terms
 563                 used for this place.
 564
 565             Returns:
 566               source_table (enum): Data source of the place. See below for possible values.
 567               category (tuple): A tuple of two strings with the primary OSM tag
 568                   and value.
 569               centroid (Point): Point position of the place.
 570               place_id (Optional[int]): Internal ID of the place. This ID may differ
 571                   for the same place between different installations.
 572               osm_object (Optional[tuple]): OSM type and ID of the place, if available.
 573               names (Optional[dict]): Dictionary of names of the place. Keys are
 574                   usually the corresponding OSM tag keys.
 575               address (Optional[dict]): Dictionary of address parts directly
 576                   attributed to the place. Keys are usually the corresponding
 577                   OSM tag keys with the `addr:` prefix removed.
 578               extratags (Optional[dict]): Dictionary of additional attributes for
 579                   the place. Usually OSM tag keys and values.
 580               housenumber (Optional[str]): House number of the place, normalised
 581                   for lookup. To get the house number in its original spelling,
 582                   use `address['housenumber']`.
 583               postcode (Optional[str]): Computed postcode for the place. To get
 584                   directly attributed postcodes, use `address['postcode']` instead.
 585               wikipedia (Optional[str]): Reference to a wikipedia site for the place.
 586                   The string has the format <language code>:<wikipedia title>.
 587               rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
 588               rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
 589               importance (Optional[float]): Relative importance of the place. This is a measure
 590                   how likely the place will be searched for.
 591               country_code (Optional[str]): Country the feature is in as
 592                   ISO 3166-1 alpha-2 country code.
 593               address_rows (Optional[AddressLines]): List of places that make up the
 594                   computed address. `None` when `address_details` parameter was False.
 595               linked_rows (Optional[AddressLines]): List of places that link to the object.
 596                   `None` when `linked_places` parameter was False.
 597               parented_rows (Optional[AddressLines]): List of direct children of the place.
 598                   `None` when `parented_places` parameter was False.
 599               name_keywords (Optional[WordInfos]): List of search words for the name of
 600                    the place. `None` when `keywords` parameter is set to False.
 601               address_keywords (Optional[WordInfos]): List of search word for the address of
 602                    the place. `None` when `keywords` parameter is set to False.
 603               bbox (Bbox): Bounding box of the full geometry of the place.
 604                    If the place is a single point, then the size of the bounding
 605                    box is guessed according to the type of place.
 606               geometry (dict): Dictionary containing the full geometry of the place
 607                    in the formats requested in the `geometry_output` parameter.
 608               distance (Optional[float]): Distance in degree from the input point.
 609         """
 610         return self._loop.run_until_complete(self._async_api.reverse(coord, **params))
 611
 612
 613     def search(self, query: str, **params: Any) -> SearchResults:
 614         """ Find a place by free-text search. Also known as forward geocoding.
 615
 616             Parameters:
 617               query: Free-form text query searching for a place.
 618
 619             Other parameters:
 620               max_results (int): Maximum number of results to return. The
 621                 actual number of results may be less. (Default: 10)
 622               min_rank (int): Lowest permissible rank for the result.
 623                 For addressable places this is the minimum
 624                 [address rank](../customize/Ranking.md#address-rank). For all
 625                 other places the [search rank](../customize/Ranking.md#search-rank)
 626                 is used.
 627               max_rank (int): Highest permissible rank for the result. See min_rank above.
 628               layers (enum): Defines the kind of data to take into account.
 629                 See [layers section](Input-Parameter-Types.md#layers) for details.
 630                 (Default: addresses and POIs)
 631               countries (list[str]): Restrict search to countries with the given
 632                 ISO 3166-1 alpha-2 country code. An empty list (the default)
 633                 disables this filter.
 634               excluded (list[int]): A list of internal IDs of places to exclude
 635                 from the search.
 636               viewbox (Optional[Bbox]): Bounding box of an area to focus search on.
 637               bounded_viewbox (bool): Consider the bounding box given in `viewbox`
 638                 as a filter and return only results within the bounding box.
 639               near (Optional[Point]): Focus search around the given point and
 640                 return results ordered by distance to the given point.
 641               near_radius (Optional[float]): Restrict results to results within
 642                 the given distance in degrees of `near` point. Ignored, when
 643                 `near` is not set.
 644               categories (list[tuple]): Restrict search to places of the given
 645                 categories. The category is the main OSM tag assigned to each
 646                 place. An empty list (the default) disables this filter.
 647               geometry_output (enum): Add the full geometry of the place to the result.
 648                 Multiple formats may be selected. Note that geometries can become
 649                 quite large. (Default: none)
 650               geometry_simplification (float): Simplification factor to use on
 651                 the geometries before returning them. The factor expresses
 652                 the tolerance in degrees from which the geometry may differ.
 653                 Topology is preserved. (Default: 0.0)
 654               address_details (bool): Add detailed information about the places
 655                 that make up the address of the requested object. (Default: False)
 656               linked_places (bool): Add detailed information about the places
 657                 that link to the result. (Default: False)
 658               parented_places (bool): Add detailed information about all places
 659                 for which the requested object is a parent, i.e. all places for
 660                 which the object provides the address details.
 661                 Only POI places can have parents. (Default: False)
 662               keywords (bool): Add detailed information about the search terms
 663                 used for this place.
 664
 665             Returns:
 666               source_table (enum): Data source of the place. See below for possible values.
 667               category (tuple): A tuple of two strings with the primary OSM tag
 668                   and value.
 669               centroid (Point): Point position of the place.
 670               place_id (Optional[int]): Internal ID of the place. This ID may differ
 671                   for the same place between different installations.
 672               osm_object (Optional[tuple]): OSM type and ID of the place, if available.
 673               names (Optional[dict]): Dictionary of names of the place. Keys are
 674                   usually the corresponding OSM tag keys.
 675               address (Optional[dict]): Dictionary of address parts directly
 676                   attributed to the place. Keys are usually the corresponding
 677                   OSM tag keys with the `addr:` prefix removed.
 678               extratags (Optional[dict]): Dictionary of additional attributes for
 679                   the place. Usually OSM tag keys and values.
 680               housenumber (Optional[str]): House number of the place, normalised
 681                   for lookup. To get the house number in its original spelling,
 682                   use `address['housenumber']`.
 683               postcode (Optional[str]): Computed postcode for the place. To get
 684                   directly attributed postcodes, use `address['postcode']` instead.
 685               wikipedia (Optional[str]): Reference to a wikipedia site for the place.
 686                   The string has the format <language code>:<wikipedia title>.
 687               rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
 688               rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
 689               importance (Optional[float]): Relative importance of the place. This is a measure
 690                   how likely the place will be searched for.
 691               country_code (Optional[str]): Country the feature is in as
 692                   ISO 3166-1 alpha-2 country code.
 693               address_rows (Optional[AddressLines]): List of places that make up the
 694                   computed address. `None` when `address_details` parameter was False.
 695               linked_rows (Optional[AddressLines]): List of places that link to the object.
 696                   `None` when `linked_places` parameter was False.
 697               parented_rows (Optional[AddressLines]): List of direct children of the place.
 698                   `None` when `parented_places` parameter was False.
 699               name_keywords (Optional[WordInfos]): List of search words for the name of
 700                    the place. `None` when `keywords` parameter is set to False.
 701               address_keywords (Optional[WordInfos]): List of search word for the address of
 702                    the place. `None` when `keywords` parameter is set to False.
 703               bbox (Bbox): Bounding box of the full geometry of the place.
 704                    If the place is a single point, then the size of the bounding
 705                    box is guessed according to the type of place.
 706               geometry (dict): Dictionary containing the full geometry of the place
 707                    in the formats requested in the `geometry_output` parameter.
 708         """
 709         return self._loop.run_until_complete(
 710                    self._async_api.search(query, **params))
 711
 712
 713     # pylint: disable=too-many-arguments
 714     def search_address(self, amenity: Optional[str] = None,
 715                        street: Optional[str] = None,
 716                        city: Optional[str] = None,
 717                        county: Optional[str] = None,
 718                        state: Optional[str] = None,
 719                        country: Optional[str] = None,
 720                        postalcode: Optional[str] = None,
 721                        **params: Any) -> SearchResults:
 722         """ Find an address using structured search.
 723
 724             Parameters:
 725               amenity: Name of a POI.
 726               street: Street and optionally housenumber of the address. If the address
 727                 does not have a street, then the place the housenumber references to.
 728               city: Postal city of the address.
 729               county: County equivalent of the address. Does not exist in all
 730                 jurisdictions.
 731               state: State or province of the address.
 732               country: Country with its full name or its ISO 3166-1 alpha-2 country code.
 733                 Do not use together with the country_code filter.
 734               postalcode: Post code or ZIP for the place.
 735
 736             Other parameters:
 737               max_results (int): Maximum number of results to return. The
 738                 actual number of results may be less. (Default: 10)
 739               min_rank (int): Lowest permissible rank for the result.
 740                 For addressable places this is the minimum
 741                 [address rank](../customize/Ranking.md#address-rank). For all
 742                 other places the [search rank](../customize/Ranking.md#search-rank)
 743                 is used.
 744               max_rank (int): Highest permissible rank for the result. See min_rank above.
 745               layers (enum): Defines the kind of data to take into account.
 746                 See [layers section](Input-Parameter-Types.md#layers) for details.
 747                 (Default: addresses and POIs)
 748               countries (list[str]): Restrict search to countries with the given
 749                 ISO 3166-1 alpha-2 country code. An empty list (the default)
 750                 disables this filter. Do not use, when the country parameter
 751                 is used.
 752               excluded (list[int]): A list of internal IDs of places to exclude
 753                 from the search.
 754               viewbox (Optional[Bbox]): Bounding box of an area to focus search on.
 755               bounded_viewbox (bool): Consider the bounding box given in `viewbox`
 756                 as a filter and return only results within the bounding box.
 757               near (Optional[Point]): Focus search around the given point and
 758                 return results ordered by distance to the given point.
 759               near_radius (Optional[float]): Restrict results to results within
 760                 the given distance in degrees of `near` point. Ignored, when
 761                 `near` is not set.
 762               categories (list[tuple]): Restrict search to places of the given
 763                 categories. The category is the main OSM tag assigned to each
 764                 place. An empty list (the default) disables this filter.
 765               geometry_output (enum): Add the full geometry of the place to the result.
 766                 Multiple formats may be selected. Note that geometries can become
 767                 quite large. (Default: none)
 768               geometry_simplification (float): Simplification factor to use on
 769                 the geometries before returning them. The factor expresses
 770                 the tolerance in degrees from which the geometry may differ.
 771                 Topology is preserved. (Default: 0.0)
 772               address_details (bool): Add detailed information about the places
 773                 that make up the address of the requested object. (Default: False)
 774               linked_places (bool): Add detailed information about the places
 775                 that link to the result. (Default: False)
 776               parented_places (bool): Add detailed information about all places
 777                 for which the requested object is a parent, i.e. all places for
 778                 which the object provides the address details.
 779                 Only POI places can have parents. (Default: False)
 780               keywords (bool): Add detailed information about the search terms
 781                 used for this place.
 782
 783             Returns:
 784               source_table (enum): Data source of the place. See below for possible values.
 785               category (tuple): A tuple of two strings with the primary OSM tag
 786                   and value.
 787               centroid (Point): Point position of the place.
 788               place_id (Optional[int]): Internal ID of the place. This ID may differ
 789                   for the same place between different installations.
 790               osm_object (Optional[tuple]): OSM type and ID of the place, if available.
 791               names (Optional[dict]): Dictionary of names of the place. Keys are
 792                   usually the corresponding OSM tag keys.
 793               address (Optional[dict]): Dictionary of address parts directly
 794                   attributed to the place. Keys are usually the corresponding
 795                   OSM tag keys with the `addr:` prefix removed.
 796               extratags (Optional[dict]): Dictionary of additional attributes for
 797                   the place. Usually OSM tag keys and values.
 798               housenumber (Optional[str]): House number of the place, normalised
 799                   for lookup. To get the house number in its original spelling,
 800                   use `address['housenumber']`.
 801               postcode (Optional[str]): Computed postcode for the place. To get
 802                   directly attributed postcodes, use `address['postcode']` instead.
 803               wikipedia (Optional[str]): Reference to a wikipedia site for the place.
 804                   The string has the format <language code>:<wikipedia title>.
 805               rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
 806               rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
 807               importance (Optional[float]): Relative importance of the place. This is a measure
 808                   how likely the place will be searched for.
 809               country_code (Optional[str]): Country the feature is in as
 810                   ISO 3166-1 alpha-2 country code.
 811               address_rows (Optional[AddressLines]): List of places that make up the
 812                   computed address. `None` when `address_details` parameter was False.
 813               linked_rows (Optional[AddressLines]): List of places that link to the object.
 814                   `None` when `linked_places` parameter was False.
 815               parented_rows (Optional[AddressLines]): List of direct children of the place.
 816                   `None` when `parented_places` parameter was False.
 817               name_keywords (Optional[WordInfos]): List of search words for the name of
 818                    the place. `None` when `keywords` parameter is set to False.
 819               address_keywords (Optional[WordInfos]): List of search word for the address of
 820                    the place. `None` when `keywords` parameter is set to False.
 821               bbox (Bbox): Bounding box of the full geometry of the place.
 822                    If the place is a single point, then the size of the bounding
 823                    box is guessed according to the type of place.
 824               geometry (dict): Dictionary containing the full geometry of the place
 825                    in the formats requested in the `geometry_output` parameter.
 826         """
 827         return self._loop.run_until_complete(
 828                    self._async_api.search_address(amenity, street, city, county,
 829                                                   state, country, postalcode, **params))
 830
 831
 832     def search_category(self, categories: List[Tuple[str, str]],
 833                         near_query: Optional[str] = None,
 834                         **params: Any) -> SearchResults:
 835         """ Find an object of a certain category near another place.
 836
 837             The near place may either be given as an unstructured search
 838             query in itself or as a geographic area through the
 839             viewbox or near parameters.
 840
 841             Parameters:
 842               categories: Restrict search to places of the given
 843                 categories. The category is the main OSM tag assigned to each
 844                 place.
 845               near_query: Optional free-text query to define the are to
 846                 restrict search to.
 847
 848             Other parameters:
 849               max_results (int): Maximum number of results to return. The
 850                 actual number of results may be less. (Default: 10)
 851               min_rank (int): Lowest permissible rank for the result.
 852                 For addressable places this is the minimum
 853                 [address rank](../customize/Ranking.md#address-rank). For all
 854                 other places the [search rank](../customize/Ranking.md#search-rank)
 855                 is used.
 856               max_rank (int): Highest permissible rank for the result. See min_rank above.
 857               layers (enum): Defines the kind of data to take into account.
 858                 See [layers section](Input-Parameter-Types.md#layers) for details.
 859                 (Default: addresses and POIs)
 860               countries (list[str]): Restrict search to countries with the given
 861                 ISO 3166-1 alpha-2 country code. An empty list (the default)
 862                 disables this filter.
 863               excluded (list[int]): A list of internal IDs of places to exclude
 864                 from the search.
 865               viewbox (Optional[Bbox]): Bounding box of an area to focus search on.
 866               bounded_viewbox (bool): Consider the bounding box given in `viewbox`
 867                 as a filter and return only results within the bounding box.
 868               near (Optional[Point]): Focus search around the given point and
 869                 return results ordered by distance to the given point.
 870               near_radius (Optional[float]): Restrict results to results within
 871                 the given distance in degrees of `near` point. Ignored, when
 872                 `near` is not set.
 873               geometry_output (enum): Add the full geometry of the place to the result.
 874                 Multiple formats may be selected. Note that geometries can become
 875                 quite large. (Default: none)
 876               geometry_simplification (float): Simplification factor to use on
 877                 the geometries before returning them. The factor expresses
 878                 the tolerance in degrees from which the geometry may differ.
 879                 Topology is preserved. (Default: 0.0)
 880               address_details (bool): Add detailed information about the places
 881                 that make up the address of the requested object. (Default: False)
 882               linked_places (bool): Add detailed information about the places
 883                 that link to the result. (Default: False)
 884               parented_places (bool): Add detailed information about all places
 885                 for which the requested object is a parent, i.e. all places for
 886                 which the object provides the address details.
 887                 Only POI places can have parents. (Default: False)
 888               keywords (bool): Add detailed information about the search terms
 889                 used for this place.
 890
 891             Returns:
 892               source_table (enum): Data source of the place. See below for possible values.
 893               category (tuple): A tuple of two strings with the primary OSM tag
 894                   and value.
 895               centroid (Point): Point position of the place.
 896               place_id (Optional[int]): Internal ID of the place. This ID may differ
 897                   for the same place between different installations.
 898               osm_object (Optional[tuple]): OSM type and ID of the place, if available.
 899               names (Optional[dict]): Dictionary of names of the place. Keys are
 900                   usually the corresponding OSM tag keys.
 901               address (Optional[dict]): Dictionary of address parts directly
 902                   attributed to the place. Keys are usually the corresponding
 903                   OSM tag keys with the `addr:` prefix removed.
 904               extratags (Optional[dict]): Dictionary of additional attributes for
 905                   the place. Usually OSM tag keys and values.
 906               housenumber (Optional[str]): House number of the place, normalised
 907                   for lookup. To get the house number in its original spelling,
 908                   use `address['housenumber']`.
 909               postcode (Optional[str]): Computed postcode for the place. To get
 910                   directly attributed postcodes, use `address['postcode']` instead.
 911               wikipedia (Optional[str]): Reference to a wikipedia site for the place.
 912                   The string has the format <language code>:<wikipedia title>.
 913               rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
 914               rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
 915               importance (Optional[float]): Relative importance of the place. This is a measure
 916                   how likely the place will be searched for.
 917               country_code (Optional[str]): Country the feature is in as
 918                   ISO 3166-1 alpha-2 country code.
 919               address_rows (Optional[AddressLines]): List of places that make up the
 920                   computed address. `None` when `address_details` parameter was False.
 921               linked_rows (Optional[AddressLines]): List of places that link to the object.
 922                   `None` when `linked_places` parameter was False.
 923               parented_rows (Optional[AddressLines]): List of direct children of the place.
 924                   `None` when `parented_places` parameter was False.
 925               name_keywords (Optional[WordInfos]): List of search words for the name of
 926                    the place. `None` when `keywords` parameter is set to False.
 927               address_keywords (Optional[WordInfos]): List of search word for the address of
 928                    the place. `None` when `keywords` parameter is set to False.
 929               bbox (Bbox): Bounding box of the full geometry of the place.
 930                    If the place is a single point, then the size of the bounding
 931                    box is guessed according to the type of place.
 932               geometry (dict): Dictionary containing the full geometry of the place
 933                    in the formats requested in the `geometry_output` parameter.
 934         """
 935         return self._loop.run_until_complete(
 936                    self._async_api.search_category(categories, near_query, **params))