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