preliminary library reference finished

[nominatim.git] / docs / library / Getting-Started.md

diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md
index 38517b14798c9c10e137c62bfdbe493b39fe68d1..6c187839f30feb8ecf22c67d64e7553acd0e59ed 100644 (file)
--- a/docs/library/Getting-Started.md
+++ b/docs/library/Getting-Started.md
@@ -9,20 +9,78 @@ also less constraints on the kinds of data that can be accessed. The library
 allows to get access to more detailed information about the objects saved
 in the database.
 
+!!! danger
+    The library interface is currently in an experimental stage. There might
+    be some smaller adjustments to the public interface until the next version.
+
+    The library also misses a proper installation routine, so some manipulation
+    of the PYTHONPATH is required. Use is only recommended for advanced Python
+    programmers at the moment.
+
 ## Installation
 
 To use the Nominatim library, you need access to a local Nominatim database.
 Follow the [installation and import instructions](../admin/) to set up your
 database.
 
-!!! warning
-    Access to the library is currently still experimental. It is not yet
-    possible to install it in the usual way via pip or inside a virtualenv.
-    To get access to the library you need to set an appropriate PYTHONPATH.
-    With the default installation, the python library can be found under
-    `/usr/local/share/nominatim/lib-python`. If you have installed Nominatim
-    under a different prefix, adapt the `/usr/local/` part accordingly.
-    You can also point the PYTHONPATH to the Nominatim source code.
-
-    A proper installation as a Python library will follow in the next
-    version.
+It is not yet possible to install it in the usual way via pip or inside a
+virtualenv. To get access to the library you need to set an appropriate
+PYTHONPATH. With the default installation, the python library can be found
+under `/usr/local/share/nominatim/lib-python`. If you have installed
+Nominatim under a different prefix, adapt the `/usr/local/` part accordingly.
+You can also point the PYTHONPATH to the Nominatim source code.
+
+
+### A simple search example
+
+To query the Nominatim database you need to first set up a connection. This
+is done by creating an Nominatim API object. This object exposes all the
+search functions of Nominatim that are also knwon from its web API.
+
+This code snippet implements a simple search for the town if 'Brugge':
+
+=== "NominatimAPIAsync"
+    ```
+    from pathlib import Path
+    import asyncio
+
+    import nominatim.api as napi
+
+    async def search(query):
+        api = napi.NominatimAPIAsync(Path('.'))
+
+        return await api.search(query)
+
+    results = asyncio.run(search('Brugge'))
+    if not results:
+        print('Cannot find Brugge')
+    else:
+        print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}')
+    ```
+
+=== "NominatimAPI"
+    ```
+    from pathlib import Path
+
+    import nominatim.api as napi
+
+    api = napi.NominatimAPI(Path('.'))
+
+    results = api.search('Brugge')
+
+    if not results:
+        print('Cannot find Brugge')
+    else:
+        print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}')
+    ```
+
+The Nonminatim API comes in two flavours: synchronous and asynchronous.
+The complete Nominatim library is written so that it can work asynchronously.
+If you have many requests to make, coroutines can speed up your applications
+significantly.
+
+For smaller scripts there is also a sychronous wrapper around the API.
+
+### Defining which database to use
+
+