osm-search/Nominatim
1
1
Fork 0
mirror of https://github.com/osm-search/Nominatim.git synced 2024-11-22 12:06:27 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3532 from lonvia/refresh-docs

Browse Source 
Update library documentation
This commit is contained in:
Sarah Hoffmann 2024-09-11 10:27:09 +02:00 committed by GitHub
commit a66c063314
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 120 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/api/Overview.md
View File

@ -1,5 +1,3 @@
### Nominatim API
!!! Attention
The current version of Nominatim implements two different search frontends:
the old PHP frontend and the new Python frontend. They have a very similar

5
docs/extra.css
View File

@ -34,3 +34,8 @@ th {
.md-footer__inner {
display: none;
}
.headerlink {
filter: grayscale(100%);
font-size: 80%;
}

12
docs/library/Configuration.md
View File

@ -1,11 +1,13 @@
# Configuration
When using Nominatim through the library, it can be configured in exactly
the same way as when running as a service. This means that you should have
created a [project directory](../admin/Import.md#creating-the-project-directory)
which contains all files belonging to the Nominatim instance. It can also contain
an `.env` file with configuration options. Setting configuration parameters
via environment variables works as well.
the same way as when running as a service. You may instantiate the library
against the [project directory](../admin/Import.md#creating-the-project-directory)
of your Nominatim installation. It contains all files belonging to the
Nominatim instance. This may include an `.env` file with configuration options.
Setting configuration parameters via environment variables works as well.
Alternatively to using the operating system's environment, a set of
configuration parameters may also be passed to the Nomiantim API object.
Configuration options are resolved in the following order:

157
docs/library/Getting-Started.md
View File

@ -1,16 +1,21 @@
# Getting Started
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. 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 Nominatim search frontend is implemented as a Python library and can as
such directly be used in Python scripts and applications. You don't need to
set up a web frontend and access it through HTTP calls. The library gives
direct access to the Nominatim database through similar search functions as
offered by the web API. In addition, it will give you a more complete and
detailed view on the search objects stored 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.
!!! warning
The Nominatim library is used for accessing a local Nominatim database.
It is not meant to be used against web services of Nominatim like the
one on https://nominatim.openstreetmap.org. If you need a Python library
to access these web services, have a look at
[GeoPy](https://geopy.readthedocs.io). Don't forget to consult the
usage policy of the service you want to use before accessing such
a web service.
## Installation
@ -19,13 +24,17 @@ 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`.
You can install the latest released version directly from pip:
pip install nominatim-api
To install the package from the source tree directly, run:
pip install packaging/nominatim-api
Usually you would want to run this in a virtual environment.
### A simple search example
## 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
@ -36,15 +45,13 @@ This code snippet implements a simple search for the town of 'Brugge':
!!! example
=== "NominatimAPIAsync"
``` python
from pathlib import Path
import asyncio
import nominatim_api as napi
async def search(query):
api = napi.NominatimAPIAsync(Path('.'))
return await api.search(query)
async with napi.NominatimAPIAsync() as api:
return await api.search(query)
results = asyncio.run(search('Brugge'))
if not results:
@ -55,13 +62,10 @@ This code snippet implements a simple search for the town of 'Brugge':
=== "NominatimAPI"
``` python
from pathlib import Path
import nominatim_api as napi
api = napi.NominatimAPI(Path('.'))
results = api.search('Brugge')
with napi.NominatimAPI() as api:
results = api.search('Brugge')
if not results:
print('Cannot find Brugge')
@ -84,7 +88,7 @@ implementations. The documentation itself will usually refer only to
available only for the synchronous or asynchronous version, this will be
explicitly mentioned.
### Defining which database to use
## Defining which database to use
The [Configuration](../admin/Import.md#configuration-setup-in-env)
section explains how Nominatim is configured using the
@ -93,76 +97,120 @@ The same configuration mechanism is used with the
Nominatim API library. You should therefore be sure you are familiar with
the section.
The constructor of the 'Nominatim API class' takes one mandatory parameter:
the path to the [project directory](../admin/Import.md#creating-the-project-directory).
You should have set up this directory as part of the Nominatim import.
Any configuration found in the `.env` file in this directory will automatically
used.
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.
Let us look up 'Brugge' in the special database named 'belgium' instead of the
standard 'nominatim' database:
There are three different ways, how configuration options can be set for
a 'Nominatim API class'. When you have set up your Nominatim database, you
have normally created a [project directory](../admin/Import.md#creating-the-project-directory)
which stores the various configuration and customization files that Nominatim
needs. You may pass the location of the project directory to your
'Nominatim API class' constructor and it will read the .env file in the
directory and set the configuration accordingly. Here is the simple search
example, using the configuration from a pre-defined project directory in
`/srv/nominatim-project`:
!!! example
=== "NominatimAPIAsync"
``` python
from pathlib import Path
import asyncio
import nominatim_api as napi
async def search(query):
async with napi.NominatimAPIAsync('/srv/nominatim-project') as api:
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[0].centroid.y}')
```
=== "NominatimAPI"
``` python
import nominatim_api as napi
with napi.NominatimAPI('/srv/nominatim-project') as api:
results = api.search('Brugge')
if not results:
print('Cannot find Brugge')
else:
print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
```
You may also configure Nominatim by setting environment variables.
Normally Nominatim will check the operating system environment. Lets
say you want to look up 'Brugge' in the special database named 'belgium' instead of the
standard 'nominatim' database. You can run the example script above like this:
```
NOMINATIM_DATABASE_DSN=pgsql:dbname=belgium python3 example.py
```
The third option to configure the library is to hand in the configuration
parameters into the 'Nominatim API class'. Changing the database would look
like this:
!!! example
=== "NominatimAPIAsync"
``` python
import asyncio
import nominatim_api as napi
config_params = {
'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
}
async def search(query):
api = napi.NominatimAPIAsync(Path('.'), environ=config_params)
return await api.search(query)
async with napi.NominatimAPIAsync(environ=config_params) as api:
return await api.search(query)
results = asyncio.run(search('Brugge'))
```
=== "NominatimAPI"
``` python
from pathlib import Path
import nominatim_api as napi
config_params = {
'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
}
api = napi.NominatimAPI(Path('.'), environ=config_params)
results = api.search('Brugge')
with napi.NominatimAPI(environ=config_params) as api:
results = api.search('Brugge')
```
### Presenting results to humans
When the `environ` parameter is given, then only configuration variables
from this dictionary will be used. The operating system's environment
variables will be ignored.
All search functions return the raw results from the database. There is no
full human-readable label. To create such a label, you need two things:
## Presenting results to humans
All search functions return full result objects from the database. Such a
result object contains lots of details: names, address information, OSM tags etc.
This gives you lots of flexibility what to do with the results.
One of the most common things to get is some kind of human-readable label
that describes the result in a compact form. Usually this would be the name
of the object and some parts of the address to explain where in the world
it is. To create such a label, you need two things:
* the address details of the place
* adapt the result to the language you wish to use for display
* all names for the label adapted to the language you wish to use for display
Again searching for 'Brugge', this time with a nicely formatted result:
!!! example
=== "NominatimAPIAsync"
``` python
from pathlib import Path
import asyncio
import nominatim_api as napi
async def search(query):
api = napi.NominatimAPIAsync(Path('.'))
return await api.search(query, address_details=True)
async with napi.NominatimAPIAsync() as api:
return await api.search(query, address_details=True)
results = asyncio.run(search('Brugge'))
@ -174,13 +222,10 @@ Again searching for 'Brugge', this time with a nicely formatted result:
=== "NominatimAPI"
``` python
from pathlib import Path
import nominatim_api as napi
api = napi.NominatimAPI(Path('.'))
results = api.search('Brugge', address_details=True)
with napi.NominatimAPI() as api:
results = api.search('Brugge', address_details=True)
locale = napi.Locales(['fr', 'en'])
for i, result in enumerate(results):
@ -236,7 +281,7 @@ Bruges, Flandre-Occidentale, Flandre, Belgique
This is a fairly simple way to create a human-readable description. The
place information in `address_rows` contains further information about each
place. For example, which OSM `adlin_level` was used, what category the place
place. For example, which OSM `admin_level` was used, what category the place
belongs to or what rank Nominatim has assigned. Use this to adapt the output
to local address formats.

3
docs/library/Low-Level-DB-Access.md
View File

@ -24,12 +24,11 @@ the placex table:
```
import asyncio
from pathlib import Path
import sqlalchemy as sa
from nominatim_api import NominatimAPIAsync
async def print_table_size():
api = NominatimAPIAsync(Path('.'))
api = NominatimAPIAsync()
async with api.begin() as conn:
cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))

7
mkdocs.yml
View File

@ -1,8 +1,12 @@
site_name: Nominatim Manual
theme:
font: false
name: material
features:
- navigation.tabs
- toc.integrate
plugins:
- privacy
copyright: Copyright © Nominatim developer community
docs_dir: docs
site_url: https://nominatim.org
@ -68,7 +72,8 @@ markdown_extensions:
alternate_style: true
- def_list
- toc:
permalink:
toc_depth: 4
permalink: 🔗
extra_css: [extra.css, styles.css]
exclude_docs: |
mk_install_instructions.py