docs/library/Getting-Started.md

   1 # Getting Started
   2
   3 The Nominatim search frontend can directly be used as a Python library in
   4 scripts and applications. When you have imported your own Nominatim database,
   5 then it is no longer necessary to run a full web service for it and access
   6 the database through http requests. With the Nominatim library it is possible
   7 to access all search functionality directly from your Python code. There are
   8 also less constraints on the kinds of data that can be accessed. The library
   9 allows to get access to more detailed information about the objects saved
  10 in the database.
  11
  12 !!! danger
  13     The library interface is currently in an experimental stage. There might
  14     be some smaller adjustments to the public interface until the next version.
  15
  16     The library also misses a proper installation routine, so some manipulation
  17     of the PYTHONPATH is required. Use is only recommended for advanced Python
  18     programmers at the moment.
  19
  20 ## Installation
  21
  22 To use the Nominatim library, you need access to a local Nominatim database.
  23 Follow the [installation and import instructions](../admin/) to set up your
  24 database.
  25
  26 It is not yet possible to install it in the usual way via pip or inside a
  27 virtualenv. To get access to the library you need to set an appropriate
  28 PYTHONPATH. With the default installation, the python library can be found
  29 under `/usr/local/share/nominatim/lib-python`. If you have installed
  30 Nominatim under a different prefix, adapt the `/usr/local/` part accordingly.
  31 You can also point the PYTHONPATH to the Nominatim source code.
  32
  33 ### A simple search example
  34
  35 To query the Nominatim database you need to first set up a connection. This
  36 is done by creating an Nominatim API object. This object exposes all the
  37 search functions of Nominatim that are also knwon from its web API.
  38
  39 This code snippet implements a simple search for the town if 'Brugge':
  40
  41 === "NominatimAPIAsync"
  42     ```
  43     from pathlib import Path
  44     import asyncio
  45
  46     import nominatim.api as napi
  47
  48     async def search(query):
  49         api = napi.NominatimAPIAsync(Path('.'))
  50
  51         return await api.search(query)
  52
  53     results = asyncio.run(search('Brugge'))
  54     if not results:
  55         print('Cannot find Brugge')
  56     else:
  57         print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}')
  58     ```
  59
  60 === "NominatimAPI"
  61     ```
  62     from pathlib import Path
  63
  64     import nominatim.api as napi
  65
  66     api = napi.NominatimAPI(Path('.'))
  67
  68     results = api.search('Brugge')
  69
  70     if not results:
  71         print('Cannot find Brugge')
  72     else:
  73         print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}')
  74     ```
  75
  76 The Nonminatim API comes in two flavours: synchronous and asynchronous.
  77 The complete Nominatim library is written so that it can work asynchronously.
  78 If you have many requests to make, coroutines can speed up your applications
  79 significantly.
  80
  81 For smaller scripts there is also a sychronous wrapper around the API.
  82
  83 ### Defining which database to use
  84
  85