mirror of
https://github.com/osm-search/Nominatim.git
synced 2024-11-27 00:49:55 +03:00
Merge pull request #2101 from lonvia/update-documentation
Update documentation
This commit is contained in:
Sarah Hoffmann
GitHub
commit
a338ba695b
@ -7,41 +7,6 @@ Please always open a separate issue for each problem. In particular, do
|
||||
not add your bugs to closed issues. They may looks similar to you but
|
||||
often are completely different from the maintainer's point of view.
|
||||
|
||||
### When Reporting Bad Search Results...
|
||||
|
||||
Please make sure to add the following information:
|
||||
|
||||
* the URL of the query that produces the bad result
|
||||
* the result you are getting
|
||||
* the expected result, preferably a link to the OSM object you want to find,
|
||||
otherwise an address that is as precise as possible
|
||||
|
||||
To get the link to the OSM object, you can try the following:
|
||||
|
||||
* go to https://openstreetmap.org
|
||||
* zoom to the area of the map where you expect the result and
|
||||
zoom in as much as possible
|
||||
* click on the question mark on the right side of the map,
|
||||
then with the queston cursor on the map where your object is located
|
||||
* find the object of interest in the list that appears on the left side
|
||||
* click on the object and report the URL back that the browser shows
|
||||
|
||||
### When Reporting Bugs...
|
||||
|
||||
Please add the following information to your issue:
|
||||
|
||||
* hardware configuration: RAM size, CPUs, kind and size of disks
|
||||
* Operating system (also mention if you are running on a cloud service)
|
||||
* Postgres and Postgis version
|
||||
* list of settings you changed in your Postgres configuration
|
||||
* Nominatim version (release version or,
|
||||
if you run from the git repo, the output of `git rev-parse HEAD`)
|
||||
* (if applicable) exact command line of the command that was causing the issue
|
||||
|
||||
Bug reports that do not include extensive information about your system,
|
||||
about the problem and about what you have been trying to debug the problem
|
||||
will be closed.
|
||||
|
||||
## Workflow for Pull Requests
|
||||
|
||||
We love to get pull requests from you. We operate the "Fork & Pull" model
|
||||
|
||||
@ -29,7 +29,7 @@ Add to your `settings/local.php`:
|
||||
@define('CONST_Osm2pgsql_Flatnode_File', '/path/to/flatnode.file');
|
||||
|
||||
Replace the second part with a suitable path on your system and make sure
|
||||
the directory exists. There should be at least 64GB of free space.
|
||||
the directory exists. There should be at least 75GB of free space.
|
||||
|
||||
## Downloading additional data
|
||||
|
||||
@ -43,7 +43,7 @@ This data is available as a binary download:
|
||||
cd $NOMINATIM_SOURCE_DIR/data
|
||||
wget https://www.nominatim.org/data/wikimedia-importance.sql.gz
|
||||
|
||||
The file is about 400MB and adds around 4GB to Nominatim database.
|
||||
The file is about 400MB and adds around 4GB to the Nominatim database.
|
||||
|
||||
!!! tip
|
||||
If you forgot to download the wikipedia rankings, you can also add
|
||||
@ -60,21 +60,21 @@ involve a GB or US postcode. This data can be optionally downloaded:
|
||||
wget https://www.nominatim.org/data/gb_postcode_data.sql.gz
|
||||
wget https://www.nominatim.org/data/us_postcode_data.sql.gz
|
||||
|
||||
## Choosing the Data to Import
|
||||
## Choosing the data to import
|
||||
|
||||
In its default setup Nominatim is configured to import the full OSM data
|
||||
set for the entire planet. Such a setup requires a powerful machine with
|
||||
at least 64GB of RAM and around 800GB of SSD hard disks. Depending on your
|
||||
at least 64GB of RAM and around 900GB of SSD hard disks. Depending on your
|
||||
use case there are various ways to reduce the amount of data imported. This
|
||||
section discusses these methods. They can also be combined.
|
||||
|
||||
### Using an extract
|
||||
|
||||
If you only need geocoding for a smaller region, then precomputed extracts
|
||||
If you only need geocoding for a smaller region, then precomputed OSM extracts
|
||||
are a good way to reduce the database size and import time.
|
||||
[Geofabrik](https://download.geofabrik.de) offers extracts for most countries.
|
||||
They even have daily updates which can be used with the update process described
|
||||
below. There are also
|
||||
[in the next section](../Update). There are also
|
||||
[other providers for extracts](https://wiki.openstreetmap.org/wiki/Planet.osm#Downloading).
|
||||
|
||||
Please be aware that some extracts are not cut exactly along the country
|
||||
@ -128,21 +128,23 @@ The style can be changed with the configuration `CONST_Import_Style`.
|
||||
|
||||
To give you an idea of the impact of using the different styles, the table
|
||||
below gives rough estimates of the final database size after import of a
|
||||
2018 planet and after using the `--drop` option. It also shows the time
|
||||
needed for the import on a machine with 64GB RAM, 4 CPUS and SSDs. Note that
|
||||
the given sizes are just an estimate meant for comparison of style requirements.
|
||||
Your planet import is likely to be larger as the OSM data grows with time.
|
||||
2020 planet and after using the `--drop` option. It also shows the time
|
||||
needed for the import on a machine with 64GB RAM, 4 CPUS and NVME disks.
|
||||
Note that the given sizes are just an estimate meant for comparison of
|
||||
style requirements. Your planet import is likely to be larger as the
|
||||
OSM data grows with time.
|
||||
|
||||
style | Import time | DB size | after drop
|
||||
----------|--------------|------------|------------
|
||||
admin | 5h | 190 GB | 20 GB
|
||||
street | 42h | 400 GB | 180 GB
|
||||
address | 59h | 500 GB | 260 GB
|
||||
full | 80h | 575 GB | 300 GB
|
||||
extratags | 80h | 585 GB | 310 GB
|
||||
admin | 4h | 215 GB | 20 GB
|
||||
street | 22h | 440 GB | 185 GB
|
||||
address | 36h | 545 GB | 260 GB
|
||||
full | 54h | 640 GB | 330 GB
|
||||
extratags | 54h | 650 GB | 340 GB
|
||||
|
||||
You can also customize the styles further. For a description of the
|
||||
style format see [the development section](../develop/Import.md).
|
||||
You can also customize the styles further.
|
||||
A [description of the style format](../develop/Import.md#configuring-the-import)
|
||||
can be found in the development section.
|
||||
|
||||
## Initial import of the data
|
||||
|
||||
@ -150,15 +152,17 @@ style format see [the development section](../develop/Import.md).
|
||||
First try the import with a small extract, for example from
|
||||
[Geofabrik](https://download.geofabrik.de).
|
||||
|
||||
Download the data to import and load the data with the following command
|
||||
from the build directory:
|
||||
Download the data to import. Then issue the following command
|
||||
from the **build directory** to start the import:
|
||||
|
||||
```sh
|
||||
./utils/setup.php --osm-file <data file> --all 2>&1 | tee setup.log
|
||||
```
|
||||
|
||||
***Note for full planet imports:*** Even on a perfectly configured machine
|
||||
the import of a full planet takes at least 2 days. Once you see messages
|
||||
### Notes on full planet imports
|
||||
|
||||
Even on a perfectly configured machine
|
||||
the import of a full planet takes around 2 days. Once you see messages
|
||||
with `Rank .. ETA` appear, the indexing process has started. This part takes
|
||||
the most time. There are 30 ranks to process. Rank 26 and 30 are the most complex.
|
||||
They take each about a third of the total import time. If you have not reached
|
||||
@ -167,11 +171,12 @@ configuration as it may not be optimal for the import.
|
||||
|
||||
### Notes on memory usage
|
||||
|
||||
In the first step of the import Nominatim uses osm2pgsql to load the OSM data
|
||||
into the PostgreSQL database. This step is very demanding in terms of RAM usage.
|
||||
osm2pgsql and PostgreSQL are running in parallel at this point. PostgreSQL
|
||||
blocks at least the part of RAM that has been configured with the
|
||||
`shared_buffers` parameter during [PostgreSQL tuning](Installation#postgresql-tuning)
|
||||
In the first step of the import Nominatim uses [osm2pgsql](https://osm2pgsql.org)
|
||||
to load the OSM data into the PostgreSQL database. This step is very demanding
|
||||
in terms of RAM usage. osm2pgsql and PostgreSQL are running in parallel at
|
||||
this point. PostgreSQL blocks at least the part of RAM that has been configured
|
||||
with the `shared_buffers` parameter during
|
||||
[PostgreSQL tuning](Installation#postgresql-tuning)
|
||||
and needs some memory on top of that. osm2pgsql needs at least 2GB of RAM for
|
||||
its internal data structures, potentially more when it has to process very large
|
||||
relations. In addition it needs to maintain a cache for node locations. The size
|
||||
@ -182,10 +187,10 @@ completely and leave the memory for the flatnode file. Nominatim will do this
|
||||
by default, so you do not need to configure anything in this case.
|
||||
|
||||
For imports without a flatnode file, set `--osm2pgsql-cache` approximately to
|
||||
the size of the OSM pbf file (in MB) you are importing. Make sure you leave
|
||||
enough RAM for PostgreSQL and osm2pgsql as mentioned above. If the system starts
|
||||
swapping or you are getting out-of-memory errors, reduce the cache size or
|
||||
even consider using a flatnode file.
|
||||
the size of the OSM pbf file you are importing. The size needs to be given in
|
||||
MB. Make sure you leave enough RAM for PostgreSQL and osm2pgsql as mentioned
|
||||
above. If the system starts swapping or you are getting out-of-memory errors,
|
||||
reduce the cache size or even consider using a flatnode file.
|
||||
|
||||
### Verify the import
|
||||
|
||||
@ -197,7 +202,7 @@ Run this script to verify all required tables and indices got created successful
|
||||
|
||||
### Setting up the website
|
||||
|
||||
Run the following command to set up the configuration file for the website
|
||||
Run the following command to set up the configuration file for the API frontend
|
||||
`settings/settings-frontend.php`. These settings are used in website/*.php files.
|
||||
|
||||
```sh
|
||||
|
||||
@ -57,12 +57,12 @@ A minimum of 2GB of RAM is required or installation will fail. For a full
|
||||
planet import 64GB of RAM or more are strongly recommended. Do not report
|
||||
out of memory problems if you have less than 64GB RAM.
|
||||
|
||||
For a full planet install you will need at least 800GB of hard disk space
|
||||
(take into account that the OSM database is growing fast). SSD disks
|
||||
will help considerably to speed up import and queries.
|
||||
For a full planet install you will need at least 900GB of hard disk space.
|
||||
Take into account that the OSM database is growing fast.
|
||||
Fast disks are essential. Using NVME disks is recommended.
|
||||
|
||||
Even on a well configured machine the import of a full planet takes
|
||||
at least 2 days. Without SSDs 7-8 days are more realistic.
|
||||
around 2 days. On traditional spinning disks, 7-8 days are more realistic.
|
||||
|
||||
## Tuning the PostgreSQL database
|
||||
|
||||
|
||||
@ -17,7 +17,12 @@ Clone the source from github:
|
||||
|
||||
git clone https://github.com/osm-search/nominatim-ui
|
||||
|
||||
Adapt the configuration `dist/config.js` to your needs. You need at least
|
||||
Copy the example configuration into the right place:
|
||||
|
||||
cd nominatim-ui
|
||||
cp dist/config.example.js dist/config.js
|
||||
|
||||
Now adapt the configuration to your needs. You need at least
|
||||
to change the `Nominatim_API_Endpoint` to point to your Nominatim installation.
|
||||
|
||||
Then you can just test it locally by spinning up a webserver in the `dist`
|
||||
@ -66,7 +71,7 @@ map $args $format {
|
||||
~(^|&)format= other;
|
||||
}
|
||||
|
||||
# Determine from the URI and the format parameter aboce if forwarding is needed.
|
||||
# Determine from the URI and the format parameter above if forwarding is needed.
|
||||
map $uri/$format $forward_to_ui {
|
||||
default 1; # The default is to forward.
|
||||
~^/ui 0; # If the URI point to the UI already, we are done.
|
||||
|
||||
@ -4,9 +4,9 @@ There are many different ways to update your Nominatim database.
|
||||
The following section describes how to keep it up-to-date with Pyosmium.
|
||||
For a list of other methods see the output of `./utils/update.php --help`.
|
||||
|
||||
!!! warning
|
||||
!!! important
|
||||
If you have configured a flatnode file for the import, then you
|
||||
need to keep this flatnode file around for updates as well.
|
||||
need to keep this flatnode file around for updates.
|
||||
|
||||
#### Installing the newest version of Pyosmium
|
||||
|
||||
|
||||
@ -1,19 +1,22 @@
|
||||
# Place details
|
||||
|
||||
Lookup details about a single place by id. The default output is HTML for debugging search logic and results.
|
||||
Show all details about a single place saved in the database.
|
||||
|
||||
**The details page (including JSON output) exists for debugging only and must not be downloaded automatically**, see [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).
|
||||
!!! warning
|
||||
The details page exists for debugging only. You may not use it in scripts
|
||||
or to automatically query details about a result.
|
||||
See [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).
|
||||
|
||||
|
||||
## Parameters
|
||||
|
||||
The details API supports the following two request formats:
|
||||
|
||||
```
|
||||
https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>
|
||||
``` xml
|
||||
https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>
|
||||
```
|
||||
|
||||
`osmtype` and `osmid` are required parameter. The type is one of node (N), way (W)
|
||||
`osmtype` and `osmid` are required parameters. The type is one of node (N), way (W)
|
||||
or relation (R). The id must be a number. The `class` parameter is optional and
|
||||
allows to distinguish between entries, when the corresponding OSM object has more
|
||||
than one main tag. For example, when a place is tagged with `tourism=hotel` and
|
||||
@ -23,36 +26,34 @@ to get exactly the one you want. If there are multiple places in the database
|
||||
but the `class` parameter is left out, then one of the places will be chosen
|
||||
at random and displayed.
|
||||
|
||||
```
|
||||
https://nominatim.openstreetmap.org/details?place_id=<value>
|
||||
``` xml
|
||||
https://nominatim.openstreetmap.org/details?place_id=<value>
|
||||
```
|
||||
|
||||
Placeids are assigned sequentially during Nominatim data import. The id for a place is different between Nominatim installation (servers) and changes when data gets reimported. Therefore it can't be used as permanent id and shouldn't be used in bug reports.
|
||||
Place IDs are assigned sequentially during Nominatim data import. The ID
|
||||
for a place is different between Nominatim installation (servers) and
|
||||
changes when data gets reimported. Therefore it cannot be used as
|
||||
a permanent id and shouldn't be used in bug reports.
|
||||
|
||||
|
||||
Additional optional parameters are explained below.
|
||||
|
||||
### Output format
|
||||
|
||||
* `format=[html|json]`
|
||||
|
||||
See [Place Output Formats](Output.md) for details on each format. (Default: html)
|
||||
|
||||
* `json_callback=<string>`
|
||||
|
||||
Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`.
|
||||
Only has an effect for JSON output formats.
|
||||
|
||||
* `pretty=[0|1]`
|
||||
|
||||
For JSON output will add indentation to make it more human-readable. (Default: 0)
|
||||
Add indentation to make it more human-readable. (Default: 0)
|
||||
|
||||
|
||||
### Output details
|
||||
|
||||
* `addressdetails=[0|1]`
|
||||
|
||||
Include a breakdown of the address into elements. (Default for JSON: 0, for HTML: 1)
|
||||
Include a breakdown of the address into elements. (Default: 0)
|
||||
|
||||
* `keywords=[0|1]`
|
||||
|
||||
@ -60,11 +61,16 @@ Include a list of name keywords and address keywords (word ids). (Default: 0)
|
||||
|
||||
* `linkedplaces=[0|1]`
|
||||
|
||||
Include details of places higher in the address hierarchy. E.g. for a street this is usually the city, state, postal code, country. (Default: 1)
|
||||
Include a details of places that are linked with this one. Places get linked
|
||||
together when they are different forms of the same physical object. Nominatim
|
||||
links two kinds of objects together: place nodes get linked with the
|
||||
corresponding administrative boundaries. Waterway relations get linked together with their
|
||||
members.
|
||||
(Default: 1)
|
||||
|
||||
* `hierarchy=[0|1]`
|
||||
|
||||
Include details of places lower in the address hierarchy. E.g. for a city this usually a list of streets, suburbs, rivers. (Default for JSON: 0, for HTML: 1)
|
||||
Include details of places lower in the address hierarchy. (Default: 0)
|
||||
|
||||
* `group_hierarchy=[0|1]`
|
||||
|
||||
@ -72,7 +78,7 @@ For JSON output will group the places by type. (Default: 0)
|
||||
|
||||
* `polygon_geojson=[0|1]`
|
||||
|
||||
Include geometry of result. (Default for JSON: 0, for HTML: 1)
|
||||
Include geometry of result. (Default: 0)
|
||||
|
||||
### Language of results
|
||||
|
||||
@ -86,10 +92,6 @@ comma-separated list of language codes.
|
||||
|
||||
## Examples
|
||||
|
||||
##### HTML
|
||||
|
||||
[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407)
|
||||
|
||||
##### JSON
|
||||
|
||||
[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json)
|
||||
|
||||
@ -56,6 +56,21 @@ specified in the "Accept-Language" HTTP header.
|
||||
Either use a standard RFC2616 accept-language string or a simple
|
||||
comma-separated list of language codes.
|
||||
|
||||
### Polygon output
|
||||
|
||||
* `polygon_geojson=1`
|
||||
* `polygon_kml=1`
|
||||
* `polygon_svg=1`
|
||||
* `polygon_text=1`
|
||||
|
||||
Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these
|
||||
options can be used at a time. (Default: 0)
|
||||
|
||||
* `polygon_threshold=0.0`
|
||||
|
||||
Return a simplified version of the output geometry. The parameter is the
|
||||
tolerance in degrees with which the geometry may differ from the original
|
||||
geometry. Topology is preserved in the result. (Default: 0.0)
|
||||
|
||||
### Other
|
||||
|
||||
|
||||
@ -2,12 +2,10 @@
|
||||
|
||||
The [/reverse](Reverse.md), [/search](Search.md) and [/lookup](Lookup.md)
|
||||
API calls produce very similar output which is explained in this section.
|
||||
There is one section for each format which is selectable via the `format`
|
||||
parameter.
|
||||
There is one section for each format. The format correspond to what was
|
||||
selected via the `format` parameter.
|
||||
|
||||
## Formats
|
||||
|
||||
### JSON
|
||||
## JSON
|
||||
|
||||
The JSON format returns an array of places (for search and lookup) or
|
||||
a single place (for reverse) of the following format:
|
||||
@ -41,13 +39,13 @@ a single place (for reverse) of the following format:
|
||||
"wikipedia": "en:London",
|
||||
"population": "8416535"
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The possible fields are:
|
||||
|
||||
* `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
|
||||
* `osm_type`, `osm_id` - reference to the OSM object
|
||||
* `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
|
||||
* `boundingbox` - area of corner coordinates ([see notes](#boundingbox))
|
||||
* `lat`, `lon` - latitude and longitude of the centroid of the object
|
||||
* `display_name` - full comma-separated address
|
||||
@ -62,22 +60,22 @@ The possible fields are:
|
||||
* `geojson`, `svg`, `geotext`, `geokml` - full geometry
|
||||
(only with the appropriate `polygon_*` parameter)
|
||||
|
||||
### JSONv2
|
||||
## JSONv2
|
||||
|
||||
This is the same as the JSON format with two changes:
|
||||
|
||||
* `class` renamed to `category`
|
||||
* additional field `place_rank` with the search rank of the object
|
||||
|
||||
### GeoJSON
|
||||
## GeoJSON
|
||||
|
||||
This format follows the [RFC7946](https://geojson.org). Every feature includes
|
||||
a bounding box (`bbox`).
|
||||
|
||||
The feature list has the following fields:
|
||||
The properties object has the following fields:
|
||||
|
||||
* `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
|
||||
* `osm_type`, `osm_id` - reference to the OSM object
|
||||
* `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
|
||||
* `category`, `type` - key and value of the main OSM tag
|
||||
* `display_name` - full comma-separated address
|
||||
* `place_rank` - class search rank
|
||||
@ -92,13 +90,13 @@ The feature list has the following fields:
|
||||
Use `polygon_geojson` to output the full geometry of the object instead
|
||||
of the centroid.
|
||||
|
||||
### GeocodeJSON
|
||||
## GeocodeJSON
|
||||
|
||||
The GeocodeJSON format follows the
|
||||
[GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
|
||||
The following feature attributes are implemented:
|
||||
|
||||
* `osm_type`, `osm_id` - reference to the OSM object (unofficial extension)
|
||||
* `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference))
|
||||
* `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
|
||||
* `label` - full comma-separated address
|
||||
* `name` - localised name of the place
|
||||
@ -110,18 +108,18 @@ The following feature attributes are implemented:
|
||||
Use `polygon_geojson` to output the full geometry of the object instead
|
||||
of the centroid.
|
||||
|
||||
### XML
|
||||
## XML
|
||||
|
||||
The XML response returns one or more place objects in slightly different
|
||||
formats depending on the API call.
|
||||
|
||||
#### Reverse
|
||||
### Reverse
|
||||
|
||||
```
|
||||
<reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
|
||||
attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
|
||||
querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
|
||||
<result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
|
||||
<result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY" place_rank="15" address_rank="15"
|
||||
lat="48.9467562" lon="11.4038717"
|
||||
boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
|
||||
Bavaria, Germany
|
||||
@ -148,7 +146,7 @@ attribution to OSM and the original querystring.
|
||||
The place information can be found in the `result` element. The attributes of that element contain:
|
||||
|
||||
* `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
|
||||
* `osm_type`, `osm_id` - reference to the OSM object
|
||||
* `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
|
||||
* `ref` - content of `ref` tag if it exists
|
||||
* `lat`, `lon` - latitude and longitude of the centroid of the object
|
||||
* `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
|
||||
@ -159,14 +157,14 @@ The full address of the result can be found in the content of the
|
||||
Additional information requested with `addressdetails=1`, `extratags=1` and
|
||||
`namedetails=1` can be found in extra elements.
|
||||
|
||||
#### Search and Lookup
|
||||
### Search and Lookup
|
||||
|
||||
```
|
||||
<searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
|
||||
attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
|
||||
querystring="london" polygon="false" exclude_place_ids="100149"
|
||||
more_url="https://nominatim.openstreetmap.org/search.php?q=london&addressdetails=1&extratags=1&exclude_place_ids=100149&format=xml&accept-language=en-US%2Cen%3Bq%3D0.7%2Cde%3Bq%3D0.3">
|
||||
<place place_id="100149" osm_type="node" osm_id="107775" place_rank="15"
|
||||
<place place_id="100149" osm_type="node" osm_id="107775" place_rank="15" address_rank="15"
|
||||
boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
|
||||
display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
|
||||
class="place" type="city" importance="0.9654895765402"
|
||||
@ -203,11 +201,12 @@ The place information can be found in the `place` elements, of which there may
|
||||
be more than one. The attributes of that element contain:
|
||||
|
||||
* `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
|
||||
* `osm_type`, `osm_id` - reference to the OSM object
|
||||
* `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
|
||||
* `ref` - content of `ref` tag if it exists
|
||||
* `lat`, `lon` - latitude and longitude of the centroid of the object
|
||||
* `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
|
||||
* `place_rank` - class search rank
|
||||
* `place_rank` - class [search rank](../develop/Ranking#search-rank)
|
||||
* `address_rank` - place [address rank](../develop/Ranking#address-rank)
|
||||
* `display_name` - full comma-separated address
|
||||
* `class`, `type` - key and value of the main OSM tag
|
||||
* `importance` - computed importance rank
|
||||
@ -217,17 +216,19 @@ When `addressdetails=1` is requested, the localised address parts appear
|
||||
as subelements with the type of the address part.
|
||||
|
||||
Additional information requested with `extratags=1` and `namedetails=1` can
|
||||
be found in extra elements as sub-element of each place.
|
||||
be found in extra elements as sub-element of `extratags` and `namedetails`
|
||||
respectively.
|
||||
|
||||
|
||||
## Notes on field values
|
||||
|
||||
### place_id is not a persistent id
|
||||
|
||||
The `place_id` is created when a Nominatim database gets installed. A
|
||||
single place will have a different value on another server or even when
|
||||
the same data gets re-imported. It's thus not useful to treat it as
|
||||
permanent for later use.
|
||||
The `place_id` is an internal identifier that is assigned data is imported
|
||||
into a Nominatim database. The same OSM object will have a different value
|
||||
on another server. It may even change its ID on the same server when it is
|
||||
removed and reimported while updating the database with fresh OSM data.
|
||||
It is thus not useful to treat it as permanent for later use.
|
||||
|
||||
The combination `osm_type`+`osm_id` is slighly better but remember in
|
||||
OpenStreetMap mappers can delete, split, recreate places (and those
|
||||
@ -236,20 +237,40 @@ Places can also change their meaning without changing their `osm_id`,
|
||||
e.g. when a restaurant is retagged as supermarket. For a more in-depth
|
||||
discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
|
||||
|
||||
Nominatim merges some places (e.g. center node of a city with the boundary
|
||||
relation) so `osm_type`+`osm_id`+`class_name` would be more unique.
|
||||
If you need an ID that is consistent over multiple installations of Nominatim,
|
||||
then you should use the combination of `osm_type`+`osm_id`+`class`.
|
||||
|
||||
### OSM reference
|
||||
|
||||
Nominatim may sometimes return special objects that do not correspond directly
|
||||
to an object in OpenStreetMap. These are:
|
||||
|
||||
* **Postcodes**. Nominatim returns an postcode point created from all mapped
|
||||
postcodes of the same name. The class and type of these object is `place=postcdode`.
|
||||
No `osm_type` and `osm_id` are included in the result.
|
||||
* **Housenumber interpolations**. Nominatim returns a single interpolated
|
||||
housenumber from the interpolation way. The class and type are `place=house`
|
||||
and `osm_type` and `osm_id` correspond to the interpolation way in OSM.
|
||||
* **TIGER housenumber.** Nominatim returns a single interpolated housenumber
|
||||
from the TIGER data. The class and type are `place=house`
|
||||
and `osm_type` and `osm_id` correspond to the street mentioned in the result.
|
||||
|
||||
Please note that the `osm_type` and `osm_id` returned may be changed in the
|
||||
future. You should not expect to only find `node`, `way` and `relation` for
|
||||
the type.
|
||||
|
||||
### boundingbox
|
||||
|
||||
Comma separated list of min latitude, max latitude, min longitude, max longitude.
|
||||
The whole planet would be `-90,90,-180,180`.
|
||||
|
||||
Can we used to pan and center the map on the result, for example with leafletjs
|
||||
Can be used to pan and center the map on the result, for example with leafletjs
|
||||
mapping library
|
||||
`map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
|
||||
|
||||
Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
|
||||
essentially covering the planet (See [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
|
||||
essentially covering the entire planet
|
||||
(see [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
|
||||
|
||||
### addressdetails
|
||||
|
||||
|
||||
@ -1,36 +1,48 @@
|
||||
# Reverse Geocoding
|
||||
|
||||
Reverse geocoding generates an address from a latitude and longitude or from
|
||||
an OSM object.
|
||||
Reverse geocoding generates an address from a latitude and longitude.
|
||||
|
||||
## How it works
|
||||
|
||||
The reveser geocoding API does not exactly compute the address for the
|
||||
coordinate it receives. It works by finding the closest suitable OSM object
|
||||
and returning its address information. This may occasionally lead to
|
||||
unexpected results.
|
||||
|
||||
First of all, Nominatim only includes OSM objects in
|
||||
its index that are suitable for searching. Small, unnamed paths for example
|
||||
are missing from the database and can therefore not be used for reverse
|
||||
geocoding either.
|
||||
|
||||
The other issue to be aware of is that the closest OSM object may not always
|
||||
have a similar enough address to the coordinate you were requesting. For
|
||||
example, in dense city areas it may belong to a completely different street.
|
||||
|
||||
|
||||
## Parameters
|
||||
|
||||
The main format of the reverse API is
|
||||
|
||||
```
|
||||
https://nominatim.openstreetmap.org/reverse?<query>
|
||||
https://nominatim.openstreetmap.org/reverse?lat=<value>&lon=<value>&<params>
|
||||
```
|
||||
|
||||
There are two ways how the requested location can be specified:
|
||||
where `lat` and `lon` are latitude and longitutde of a coordinare in WGS84
|
||||
projection. The API returns exactly one result or an error when the coordinate
|
||||
is in an area with no OSM data coverage.
|
||||
|
||||
* `lat=<value>` `lon=<value>`
|
||||
Additional paramters are accepted as listed below.
|
||||
|
||||
A geographic location to generate an address for. The coordiantes must be
|
||||
in WGS84 format.
|
||||
|
||||
* `osm_type=[N|W|R]` `osm_id=<value>`
|
||||
|
||||
A specific OSM node(N), way(W) or relation(R) to return an address for.
|
||||
|
||||
In both cases exactly one object is returned. The two input parameters cannot
|
||||
be used at the same time. Both accept the additional optional parameters listed
|
||||
below.
|
||||
!!! warning "Deprecation warning"
|
||||
The reverse API used to allow address lookup for a single OSM object by
|
||||
its OSM id. This use is now deprecated. Use the [Address Lookup API](../Lookup)
|
||||
instead.
|
||||
|
||||
### Output format
|
||||
|
||||
* `format=[xml|json|jsonv2|geojson|geocodejson]`
|
||||
|
||||
See [Place Output Formats](Output.md) for details on each format. (Default: html)
|
||||
See [Place Output Formats](Output.md) for details on each format. (Default: xml)
|
||||
|
||||
* `json_callback=<string>`
|
||||
|
||||
@ -69,8 +81,9 @@ comma-separated list of language codes.
|
||||
|
||||
* `zoom=[0-18]`
|
||||
|
||||
Level of detail required for the address. Default: 18. This is a number that corresponds
|
||||
roughly to the zoom level used in map frameworks like Leaflet.js, Openlayers etc.
|
||||
Level of detail required for the address. Default: 18. This is a number that
|
||||
corresponds roughly to the zoom level used in XYZ tile sources in frameworks
|
||||
like Leaflet.js, Openlayers etc.
|
||||
In terms of address details the zoom levels are as follows:
|
||||
|
||||
zoom | address detail
|
||||
@ -97,7 +110,7 @@ options can be used at a time. (Default: 0)
|
||||
|
||||
* `polygon_threshold=0.0`
|
||||
|
||||
Simplify the output geometry before returning. The parameter is the
|
||||
Return a simplified version of the output geometry. The parameter is the
|
||||
tolerance in degrees with which the geometry may differ from the original
|
||||
geometry. Topology is preserved in the result. (Default: 0.0)
|
||||
|
||||
|
||||
@ -1,30 +1,27 @@
|
||||
# Search queries
|
||||
|
||||
The search API allows you to look up a location from a textual description.
|
||||
Nominatim supports structured as well as free-form search queries.
|
||||
The search API allows you to look up a location from a textual description
|
||||
or address. Nominatim supports structured and free-form search queries.
|
||||
|
||||
The search query may also contain
|
||||
[special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
|
||||
which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => `amenity=pub`).
|
||||
Note that this only limits the items to be found, it's not suited to return complete
|
||||
lists of OSM objects of a specific type. For those use [Overpass API](https://overpass-api.de/).
|
||||
This can be used to narrow down the kind of objects to be returned.
|
||||
|
||||
!!! warning
|
||||
Special phrases are not suitable to query all objects of a certain type in an
|
||||
area. Nominatim will always just return a collection of the best matches. To
|
||||
download OSM data by object type, use the [Overpass API](https://overpass-api.de/).
|
||||
|
||||
## Parameters
|
||||
|
||||
The search API has the following two formats:
|
||||
|
||||
```
|
||||
https://nominatim.openstreetmap.org/search/<query>?<params>
|
||||
```
|
||||
|
||||
This format only accepts a free-form query string where the
|
||||
parts of the query are separated by slashes.
|
||||
The search API has the following format:
|
||||
|
||||
```
|
||||
https://nominatim.openstreetmap.org/search?<params>
|
||||
```
|
||||
|
||||
In this form, the query may be given through two different sets of parameters:
|
||||
The search term may be specified with two different sets of parameters:
|
||||
|
||||
* `q=<query>`
|
||||
|
||||
@ -46,13 +43,13 @@ In this form, the query may be given through two different sets of parameters:
|
||||
Structured requests are faster but are less robust against alternative
|
||||
OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**.
|
||||
|
||||
All three query forms accept the additional parameters listed below.
|
||||
Both query forms accept the additional parameters listed below.
|
||||
|
||||
### Output format
|
||||
|
||||
* `format=[html|xml|json|jsonv2|geojson|geocodejson]`
|
||||
* `format=[xml|json|jsonv2|geojson|geocodejson]`
|
||||
|
||||
See [Place Output Formats](Output.md) for details on each format. (Default: html)
|
||||
See [Place Output Formats](Output.md) for details on each format. (Default: jsonv2)
|
||||
|
||||
* `json_callback=<string>`
|
||||
|
||||
@ -96,16 +93,16 @@ Limit search results to one or more countries. `<countrycode>` must be the
|
||||
e.g. `gb` for the United Kingdom, `de` for Germany.
|
||||
|
||||
Each place in Nominatim is assigned to one country code based
|
||||
on `admin_level=2` tags, in rare cases to none (for example in
|
||||
international waters outside any country).
|
||||
on OSM country boundaries. In rare cases a place may not be in any country
|
||||
at all, for example, in international waters.
|
||||
|
||||
* `exclude_place_ids=<place_id,[place_id],[place_id]`
|
||||
|
||||
If you do not want certain OSM objects to appear in the search
|
||||
result, give a comma separated list of the `place_id`s you want to skip.
|
||||
This can be used to broaden search results. For example, if a previous
|
||||
query only returned a few results, then including those here would cause
|
||||
the search to return other, less accurate, matches (if possible).
|
||||
This can be used to retrieve additional search results. For example, if a
|
||||
previous query only returned a few results, then including those here would
|
||||
cause the search to return other, less accurate, matches (if possible).
|
||||
|
||||
|
||||
* `limit=<integer>`
|
||||
@ -122,10 +119,11 @@ are accepted as long as they span a real box. `x` is longitude,
|
||||
|
||||
* `bounded=[0|1]`
|
||||
|
||||
When a viewbox is given, restrict the result to items contained with that
|
||||
When a viewbox is given, restrict the result to items contained within that
|
||||
viewbox (see above). When `viewbox` and `bounded=1` are given, an amenity
|
||||
only search is allowed. In this case, give the special keyword for the
|
||||
amenity in square brackets, e.g. `[pub]`. (Default: 0)
|
||||
only search is allowed. Give the special keyword for the amenity in square
|
||||
brackets, e.g. `[pub]` and a selection of objects of this type is returned.
|
||||
There is no guarantee that the result is complete. (Default: 0)
|
||||
|
||||
|
||||
### Polygon output
|
||||
@ -140,7 +138,7 @@ options can be used at a time. (Default: 0)
|
||||
|
||||
* `polygon_threshold=0.0`
|
||||
|
||||
Simplify the output geometry before returning. The parameter is the
|
||||
Return a simplified version of the output geometry. The parameter is the
|
||||
tolerance in degrees with which the geometry may differ from the original
|
||||
geometry. Topology is preserved in the result. (Default: 0.0)
|
||||
|
||||
@ -154,13 +152,11 @@ address to identify your requests. See Nominatim's [Usage Policy](https://operat
|
||||
* `dedupe=[0|1]`
|
||||
|
||||
Sometimes you have several objects in OSM identifying the same place or
|
||||
object in reality. The simplest case is a street being split in many
|
||||
object in reality. The simplest case is a street being split into many
|
||||
different OSM ways due to different characteristics. Nominatim will
|
||||
attempt to detect such duplicates and only return one match unless
|
||||
this parameter is set to 0. (Default: 1)
|
||||
|
||||
|
||||
|
||||
* `debug=[0|1]`
|
||||
|
||||
Output assorted developer debug information. Data on internals of Nominatim's
|
||||
|
||||
@ -25,7 +25,7 @@ following packages should get you started:
|
||||
|
||||
## Prerequisites for testing and documentation
|
||||
|
||||
The Nominatim tests suite consists of behavioural tests (using behave) and
|
||||
The Nominatim test suite consists of behavioural tests (using behave) and
|
||||
unit tests (using PHPUnit). It has the following additional requirements:
|
||||
|
||||
* [behave test framework](https://behave.readthedocs.io) >= 1.2.5
|
||||
@ -85,7 +85,7 @@ All tests are located in the `\test` directory.
|
||||
Some of the behavioural test expect a test database to be present. You need at
|
||||
least 2GB RAM and 10GB disk space to create the database.
|
||||
|
||||
First create a separate directory for the test DB and Fetch the test planet
|
||||
First create a separate directory for the test DB and fetch the test planet
|
||||
data and the Tiger data for South Dakota:
|
||||
|
||||
```
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# OSM Data Import
|
||||
|
||||
OSM data is initially imported using osm2pgsql. Nominatim uses its own data
|
||||
output style 'gazetteer', which differs from the output style created for
|
||||
map rendering.
|
||||
OSM data is initially imported using [osm2pgsql](https://osm2pgsql.org).
|
||||
Nominatim uses its own data output style 'gazetteer', which differs from the
|
||||
output style created for map rendering.
|
||||
|
||||
## Database Layout
|
||||
|
||||
|
||||
@ -7,7 +7,7 @@ different purposes, which are explained in this chapter.
|
||||
## Search rank
|
||||
|
||||
The search rank describes the extent and importance of a place. It is used
|
||||
when ranking search result. Simply put, if there are two results for a
|
||||
when ranking search results. Simply put, if there are two results for a
|
||||
search query which are otherwise equal, then the result with the _lower_
|
||||
search rank will be appear higher in the result list.
|
||||
|
||||
|
||||
@ -27,7 +27,7 @@ This test directory is sturctured as follows:
|
||||
|
||||
## PHP Unit Tests (`test/php`)
|
||||
|
||||
Unit tests can be found in the php/ directory and tests selected php functions.
|
||||
Unit tests can be found in the php/ directory. They test selected php functions.
|
||||
Very low coverage.
|
||||
|
||||
To execute the test suite run
|
||||
@ -89,7 +89,7 @@ feature of behave which comes in handy when writing new tests.
|
||||
### API Tests (`test/bdd/api`)
|
||||
|
||||
These tests are meant to test the different API endpoints and their parameters.
|
||||
They require a to import several datasets into a test database.
|
||||
They require to import several datasets into a test database.
|
||||
See the [Development Setup chapter](Development-Environment.md#preparing-the-test-database)
|
||||
for instructions on how to set up this database.
|
||||
|
||||
@ -128,7 +128,7 @@ the [phpcov](https://github.com/sebastianbergmann/phpcov) tool:
|
||||
|
||||
These tests check the import and update of the Nominatim database. They do not
|
||||
test the correctness of osm2pgsql. Each test will write some data into the `place`
|
||||
table (and optionally `the planet_osm_*` tables if required) and then run
|
||||
table (and optionally the `planet_osm_*` tables if required) and then run
|
||||
Nominatim's processing functions on that.
|
||||
|
||||
These tests need to create their own test databases. By default they will be
|
||||
@ -139,4 +139,4 @@ needs superuser rights for postgres.
|
||||
### Import Tests (`test/bdd/osm2pgsql`)
|
||||
|
||||
These tests check that data is imported correctly into the place table. They
|
||||
use the same template database as the Indexing tests, so the same remarks apply.
|
||||
use the same template database as the DB Creation tests, so the same remarks apply.
|
||||
|
||||
@ -9,14 +9,14 @@ the address computation and the search frontend.
|
||||
The __data import__ stage reads the raw OSM data and extracts all information
|
||||
that is useful for geocoding. This part is done by osm2pgsql, the same tool
|
||||
that can also be used to import a rendering database. It uses the special
|
||||
gazetteer output plugin in `osm2pgsql/output-gazetter.[ch]pp`. The result of
|
||||
gazetteer output plugin in `osm2pgsql/src/output-gazetter.[ch]pp`. The result of
|
||||
the import can be found in the database table `place`.
|
||||
|
||||
The __address computation__ or __indexing__ stage takes the data from `place`
|
||||
and adds additional information needed for geocoding. It ranks the places by
|
||||
importance, links objects that belong together and computes addresses and
|
||||
the search index. Most of this work is done in PL/pgSQL via database triggers
|
||||
and can be found in the file `sql/functions.sql`.
|
||||
and can be found in the files in the `sql/functions/` directory.
|
||||
|
||||
The __search frontend__ implements the actual API. It takes search
|
||||
and reverse geocoding queries from the user, looks up the data and
|
||||
|
||||
Loading…
Reference in New Issue
Block a user