The Nominatim search frontend can directly be used as a Python library in
scripts and applications. When you have imported your own Nominatim database,
then it is no longer necessary to run a full web service for it and access
-the database through http requests. With the Nominatim library it is possible
-to access all search functionality directly from your Python code. There are
+the database through http requests. There are
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.
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.
+Follow the [installation](../admin/Installation.md) and
+[import](../admin/Import.md) instructions to set up your database.
+
+The Nominatim frontend library is contained in the Python package `nominatim-api`.
+To install the package from the source tree directly, run:
+
+ pip install packaging/nominatim-api
-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.
+Usually you would want to run this in a virtual environment.
### A simple search example
is done by creating an Nominatim API object. This object exposes all the
search functions of Nominatim that are also known from its web API.
-This code snippet implements a simple search for the town if 'Brugge':
+This code snippet implements a simple search for the town of 'Brugge':
!!! example
=== "NominatimAPIAsync"
from pathlib import Path
import asyncio
- import nominatim.api as napi
+ import nominatim_api as napi
async def search(query):
api = napi.NominatimAPIAsync(Path('.'))
if not results:
print('Cannot find Brugge')
else:
- print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}')
+ print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
```
=== "NominatimAPI"
``` python
from pathlib import Path
- import nominatim.api as napi
+ import nominatim_api as napi
api = napi.NominatimAPI(Path('.'))
if not results:
print('Cannot find Brugge')
else:
- print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}')
+ print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
```
The Nominatim library is designed around
For smaller scripts there is also a synchronous wrapper around the API. By
using `NominatimAPI`, you get exactly the same interface using classic functions.
-The examples in this chapter will always show how work with both of the
-implementations. The documentation itself will refer usually only to
+The examples in this chapter will always show-case both
+implementations. The documentation itself will usually refer only to
'Nominatim API class' when both flavours are meant. If a functionality is
available only for the synchronous or asynchronous version, this will be
explicitly mentioned.
Any configuration found in the `.env` file in this directory will automatically
used.
-The second way to configure your Nominatim setup is through environment variables.
+You may also configure Nominatim by setting environment variables.
Normally, Nominatim will check the operating system environment. This can be
overwritten by giving the constructor a dictionary of configuration parameters.
from pathlib import Path
import asyncio
- import nominatim.api as napi
+ import nominatim_api as napi
config_params = {
'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
``` python
from pathlib import Path
- import nominatim.api as napi
+ import nominatim_api as napi
config_params = {
'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
from pathlib import Path
import asyncio
- import nominatim.api as napi
+ import nominatim_api as napi
async def search(query):
api = napi.NominatimAPIAsync(Path('.'))
``` python
from pathlib import Path
- import nominatim.api as napi
+ import nominatim_api as napi
api = napi.NominatimAPI(Path('.'))
places in `address_rows` contain all possible name translation for each row.
The library has a helper class `Locale` which helps extracting a name of a
-place in the preferred language. It gets a list of language code in the
-order of preference. So
+place in the preferred language. It takes a single parameter with a list
+of language codes in the order of preference. So
``` python
locale = napi.Locale(['fr', 'en'])
not possible, it tries English and eventually falls back to the default `name`
or `ref`.
-The Locale object can be applied to a name dictionary to return the best-matching
+The `Locale` object can be applied to a name dictionary to return the best-matching
name out of it:
``` python
projects / nominatim.git / blobdiff