### PHP "open_basedir restriction in effect" warnings
- `PHP Warning: file_get_contents(): open_basedir restriction in effect.`
+ PHP Warning: file_get_contents(): open_basedir restriction in effect.
-You need to adjust the [open_basedir](http://www.php.net/manual/en/ini.core.php#ini.open-basedir) setting
+You need to adjust the [open_basedir](https://www.php.net/manual/en/ini.core.php#ini.open-basedir) setting
in your PHP configuration (`php.ini file`). By default this setting may look like this:
open_basedir = /srv/http/:/home/:/tmp/:/usr/share/pear/
-Either add reported directories to the list or disable this setting temporarily by
+Either add reported directories to the list or disable this setting temporarily by
dding ";" at the beginning of the line. Don't forget to enable this setting again
once you are done with the PHP command line operations.
You should set the default time zone as instructed in the warning in
your `php.ini` file. Find the entry about timezone and set it to
something like this:
-
+
; Defines the default timezone used by the date functions
- ; http://php.net/date.timezone
+ ; https://php.net/date.timezone
date.timezone = 'America/Denver'
Or
### nominatim UPDATE failed: ERROR: buffer 179261 is not owned by resource owner Portal
-Several users [reported this](https://github.com/openstreetmap/Nominatim/issues/1168) during the initial import of the database. It's
-something Postgresql internal Nominatim doesn't control. And Postgresql forums
+Several users [reported this](https://github.com/openstreetmap/Nominatim/issues/1168) during the initial import of the database. It's
+something PostgreSQL internal Nominatim doesn't control. And PostgreSQL forums
suggest it's threading related but definitely some kind of crash of a process.
Users reported either rebooting the server, different hardware or just trying
-the import again worked.
+the import again worked.
### The website shows: "Could not get word tokens"
CONTEXT: PL/pgSQL function make_standard_name(text) line 5 at assignment]
```
-The Postgresql database, i.e. user postgres, needs to have access to that file.
+The PostgreSQL database, i.e. user `postgres`, needs to have access to that file.
The permission need to be read & executable by everybody, e.g.
### Setup.php fails with "DB Error: extension not found"
-Make sure you have the Postgres extensions hstore and postgis installed.
+Make sure you have the PostgreSQL extensions "hstore" and "postgis" installed.
See the installation instruction for a full list of required packages.
The message is a bit misleading as PHP needs to load the file `DB.php` and
instead re-loads Nominatim's `db.php`. To solve this make sure you
-have the [Pear module 'DB'](http://pear.php.net/package/DB/) installed.
+have the [Pear module 'DB'](https://pear.php.net/package/DB/) installed.
sudo pear install DB
once per day and apply them **separately** using
./utils/update.php --import-diff <filename> --index
-
+
See [this issue](https://github.com/openstreetmap/Nominatim/issues/60#issuecomment-18679446)
for a script that runs the updates using osmosis.
### Wikipedia rankings
Wikipedia can be used as an optional auxiliary data source to help indicate
-the importance of osm features. Nominatim will work without this information
+the importance of OSM features. Nominatim will work without this information
but it will improve the quality of the results if this is installed.
This data is available as a binary download:
wget https://www.nominatim.org/data/wikipedia_redirect.sql.bin
Combined the 2 files are around 1.5GB and add around 30GB to the install
-size of nominatim. They also increase the install time by an hour or so.
+size of Nominatim. They also increase the install time by an hour or so.
*NOTE:* you'll need to download the Wikipedia rankings before performing
the initial import of the data if you want the rankings applied to the
### UK postcodes
-Nominatim can use postcodes from an external source to improve searches that involve a UK postcode. This data can be optionally downloaded:
+Nominatim can use postcodes from an external source to improve searches that involve a UK postcode. This data can be optionally downloaded:
cd $NOMINATIM_SOURCE_DIR/data
wget https://www.nominatim.org/data/gb_postcode_data.sql.gz
Please be aware that some extracts are not cut exactly along the country
boundaries. As a result some parts of the boundary may be missing which means
-that cannot compute the areas for some administrative areas.
+that Nominatim cannot compute the areas for some administrative areas.
### Dropping Data Required for Dynamic Updates
If you only want to use the Nominatim database for reverse lookups or
if you plan to use the installation only for exports to a
-[photon](http://photon.komoot.de/) database, then you can set up a database
+[photon](https://photon.komoot.de/) database, then you can set up a database
without search indexes. Add `--reverse-only` to your setup command above.
This saves about 5% of disk space.
The style can be changed with the configuration `CONST_Import_Style`.
-To give you an idea of the impact of using the different style, the table
+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 32GB RAM, 4 CPUS and SSDs. Note that
full | 80h | 575 GB | 300 GB
You can also customize the styles further. For an description of the
-style format see [the developement section](../develop/Import.md).
+style format see [the development section](../develop/Import.md).
## Initial import of the data
2/3 of RAM available. If your machine starts swapping reduce the size.
Computing word frequency for search terms can improve the performance of
-forward geocoding in particular under high load as it helps Postgres' query
+forward geocoding in particular under high load as it helps PostgreSQL's query
planner to make the right decisions. To recompute word counts run:
```sh
1. Get preprocessed TIGER 2018 data and unpack it into the
data directory in your Nominatim sources:
- cd Nominatim/data
- wget https://nominatim.org/data/tiger2018-nominatim-preprocessed.tar.gz
- tar xf tiger2018-nominatim-preprocessed.tar.gz
+```sh
+ cd Nominatim/data
+ wget https://nominatim.org/data/tiger2018-nominatim-preprocessed.tar.gz
+ tar xf tiger2018-nominatim-preprocessed.tar.gz
+```
`data-source/us-tiger/README.md` explains how the data got preprocessed.
- 2. Import the data into your Nominatim database:
+ 2. Import the data into your Nominatim database:
- ./utils/setup.php --import-tiger-data
+```sh
+ ./utils/setup.php --import-tiger-data
+```
3. Enable use of the Tiger data in your `settings/local.php` by adding:
+```
@define('CONST_Use_US_Tiger_Data', true);
+```
4. Apply the new settings:
## Updates
-There are many different possibilities to update your Nominatim database.
+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`.
If you want a different update source you will need to add some settings
to `settings/local.php`. For example, to use the daily country extracts
-diffs for Ireland from geofabrik add the following:
+diffs for Ireland from Geofabrik add the following:
// base URL of the replication service
@define('CONST_Replication_Url', 'https://download.geofabrik.de/europe/ireland-and-northern-ireland-updates');
It outputs the date where updates will start. Recheck that this date is
what you expect.
-The --init-updates command needs to be rerun whenever the replication service
+The `--init-updates` command needs to be rerun whenever the replication service
is changed.
#### Updating Nominatim
For running tests:
* [behave](http://pythonhosted.org/behave/)
- * [Psycopg2](http://initd.org/psycopg)
+ * [Psycopg2](https://initd.org/psycopg)
* [nose](https://nose.readthedocs.io)
* [phpunit](https://phpunit.de)
For running Nominatim:
- * [PostgreSQL](http://www.postgresql.org) (9.3 or later)
- * [PostGIS](http://postgis.refractions.net) (2.2 or later)
- * [PHP](http://php.net) (7.0 or later)
+ * [PostgreSQL](https://www.postgresql.org) (9.3 or later)
+ * [PostGIS](https://postgis.org) (2.2 or later)
+ * [PHP](https://php.net) (7.0 or later)
* PHP-pgsql
* PHP-intl (bundled with PHP)
- * [PEAR::DB](http://pear.php.net/package/DB)
+ * [PEAR::DB](https://pear.php.net/package/DB)
* a webserver (apache or nginx are recommended)
For running continuous updates:
- * [pyosmium](http://osmcode.org/pyosmium/)
+ * [pyosmium](https://osmcode.org/pyosmium/)
### Hardware
A minimum of 2GB of RAM is required or installation will fail. For a full
-planet import 32GB of RAM or more strongly are recommended.
+planet import 32GB of RAM or more are strongly recommended.
For a full planet install you will need at least 700GB of hard disk space
(take into account that the OSM database is growing fast). SSD disks
This page describes database migrations necessary to update existing databases
to newer versions of Nominatim.
-SQL statements should be executed from the postgres commandline. Execute
+SQL statements should be executed from the PostgreSQL commandline. Execute
`psql nominatim` to enter command line mode.
* `json_callback=<string>`
-Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`.
+Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`.
Only has an effect for JSON output formats.
* `pretty=[0|1]`
Nominatim computes the address from two sources in the OpenStreetMap data:
from administrative boundaries and from place nodes. Boundaries are the more
useful source. They precisely describe an area. So it is very clear for
-Nominatim if a point belongs to an area of not. Place nodes are more complicated.
-These are only points without any precise extend. So Nominatim has to take a
-guess and assume that an address belongs to the closest place nose it can find.
+Nominatim if a point belongs to an area or not. Place nodes are more complicated.
+These are only points without any precise extent. So Nominatim has to take a
+guess and assume that an address belongs to the closest place node it can find.
In an ideal world, Nominatim would not need the place nodes but there are
-many places on earth where there are not precise boundaries available for
+many places on earth where there are no precise boundaries available for
all parts that make up an address. This is in particular true for the more
local address parts, like villages and suburbs. Therefore it is not possible
to completely dismiss place nodes. And sometimes they sneak in where they
see a place node for which already an administrative area exists, then you
should _link_ the two by adding the node with a 'label' role to the boundary
relation. If there is no administrative area, you can add the approximate
-extend of the place and tag it place=<something> as well.
+extent of the place and tag it place=<something> as well.
#### 2. When doing reverse search, the address details have parts that don't contain the point I was looking up.
returns the closest object to the point you asked for and then returns the
address of that object. Now, if you are close to a border, then the closest
object may be across that border. When Nominatim then returns the address,
-contains the county/state/country across the border.
+it contains the county/state/country across the border.
#### 3. I get different counties/states/countries when I change the zoom parameter in the reverse query. How is that possible?
Nominatim assigns each map feature one country. Those outside any administrative
boundaries are assigned a special no-country. Continents or other super-national
-administrations (e.g. European Union, NATO, Custom unions) are not supported,
+administrations (e.g. European Union, NATO, Custom unions) are not supported,
see also [Administrative Boundary](https://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#Super-national_administrations).
#### 5. Can you return the timezone?
-See this separate OpenStreetMap-based project [Timezone Boundary Builder](https://github.com/evansiroky/timezone-boundary-builder)
+See this separate OpenStreetMap-based project [Timezone Boundary Builder](https://github.com/evansiroky/timezone-boundary-builder).
#### 6. I want to download a list of streets/restaurants of a city/region
* `json_callback=<string>`
-Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`.
+Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`.
Only has an effect for JSON output formats.
### Output details
# Place Output
-The [\reverse](Reverse.md), [\search](Search.md) and [\lookup](Lookup.md)
+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.
### GeoJSON
-This format follows the [RFC7946](http://geojson.org). Every feature includes
+This format follows the [RFC7946](https://geojson.org). Every feature includes
a bounding box (`bbox`).
The feature list has the following fields:
* `importance` - computed importance rank
* `icon` - link to class icon (if available)
* `address` - dictionary of address details (only with `addressdetails=1`)
- * `extratags` - dictionary with additional useful tags like website or maxspeed
+ * `extratags` - dictionary with additional useful tags like `website` or `maxspeed`
(only with `extratags=1`)
* `namedetails` - dictionary with full list of available names including ref etc.
```
<reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
- attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+ 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"
lat="48.9467562" lon="11.4038717"
* `lat`, `lon` - latitude and longitude of the centroid of the object
* `boundingbox` - comma-separated list of corner coordinates
-The full address address of the result can be found in the content of the
+The full address of the result can be found in the content of the
`result` element as a comma-separated list.
Additional information requested with `addressdetails=1`, `extratags=1` and
```
<searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
- attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+ 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"
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"
+ display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
class="place" type="city" importance="0.9654895765402"
icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
<extratags>
The combination `osm_type`+`osm_id` is slighly better but remember in
OpenStreetMap mappers can delete, split, recreate places (and those
-get a new `osm_id`), there is no link between those old and new id.
+get a new `osm_id`), there is no link between those old and new ids.
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).
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 paramters cannot
+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.
* `json_callback=<string>`
-Wrap json output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
+Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
Only has an effect for JSON output formats.
### Output details
<postcode>B72</postcode>
<country>United Kingdom</country>
<country_code>gb</country_code>
- </addressparts>
+ </addressparts>
</reversegeocode>
```
```json
{
"place_id":"134140761",
- "licence":"Data © OpenStreetMap contributors, ODbL 1.0. http:\/\/www.openstreetmap.org\/copyright",
+ "licence":"Data © OpenStreetMap contributors, ODbL 1.0. https:\/\/www.openstreetmap.org\/copyright",
"osm_type":"way",
"osm_id":"280940520",
"lat":"-34.4391708",
# Search queries
-The search API allows to look up a location from a textual description.
+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 query may also contain
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 paramters listed below.
+All three query forms accept the additional parameters listed below.
### Output format
* `json_callback=<string>`
-Wrap json output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
+Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
Only has an effect for JSON output formats.
### Output details
```xml
<searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
- <place
- place_id="1620612" osm_type="node" osm_id="452010817"
- boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
- polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"
- lat="52.5487429714954" lon="-1.81602098644987"
- display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
+ <place
+ place_id="1620612" osm_type="node" osm_id="452010817"
+ boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
+ polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"
+ lat="52.5487429714954" lon="-1.81602098644987"
+ display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
class="place" type="house">
<house_number>135</house_number>
<road>Pilkington Avenue</road>
motorway bridge. In OSM, this would be a way which is tagged with
`highway=motorway` and `bridge=yes`. This way would appear in the `place` table
once with `class` of `highway` and once with a `class` of `bridge`. Thus the
-*uique key* for `place` is (`osm_type`, `osm_id`, `class`).
+*unique key* for `place` is (`osm_type`, `osm_id`, `class`).
## Configuring the Import
other string constitutes an exact match.
The second part of the rules defines a list of values and the properties that
-apply to a successful match. Value strings may be either empty, which again
-means that thy match against any value, or describe an exact match. Prefix
+apply to a successful match. Value strings may be either empty, which
+means that they match any value, or describe an exact match. Prefix
or suffix matching of values is not possible.
For a rule to match, it has to find a valid combination of keys and values. The
match for each tag wins.
A rule where key and value are the empty string is special. This defines the
-fallback when none of the rules matches. The fallback is always used as a last
+fallback when none of the rules match. The fallback is always used as a last
resort when nothing else matches, no matter where the rule appears in the file.
Defining multiple fallback rules is not allowed. What happens in this case,
is undefined.
* `address`
- At tag to the list of address tags. If the tag starts with `addr:` or
+ Add tag to the list of address tags. If the tag starts with `addr:` or
`is_in:`, then this prefix is cut off before adding it to the list.
* `postcode`
- At the value as a postcode to the address tags. If multiple tags are
+ Add the value as a postcode to the address tags. If multiple tags are
candidate for postcodes, one wins out and the others are dropped.
* `country`
- At the value as a country code to the address tags. The value must be a
+ Add the value as a country code to the address tags. The value must be a
two letter country code, otherwise it is ignored. If there are multiple
tags that match, then one wins out and the others are dropped.
eligible to be part of an address. All other objects have an address rank
of 0.
-Note that the search rank of a place place a role in the address computation
+Note that the search rank of a place plays a role in the address computation
as well. When collecting the places that should make up the address parts
then only places are taken into account that have a lower address rank than
the search rank of the base object.
* highway nodes
* landuse that is not an area
-Other than that, the ranks can be freely assigned via the json file
+Other than that, the ranks can be freely assigned via the JSON file
defined with `CONST_Address_Level_Config` according to their type and
the country they are in.
country exists.
`tags` contains the ranks for key/value pairs. The ranks can be either a
-single number, in which case they are to search and address rank, or a tuple
+single number, in which case they are the search and address rank, or an array
of search and address rank (in that order). The value may be left empty.
Then the rank is used when no more specific value is found for the given
key.
-Countries and key/value combination may appear in multiple defintions. Just
+Countries and key/value combination may appear in multiple definitions. Just
make sure that each combination of counrty/key/value appears only once per
file. Otherwise the import will fail with a UNIQUE INDEX constraint violation
on import.
+
# Basic Architecture
-Nominatim provides geocoding based on OpenStreetMap data. It uses a Postgresql
+Nominatim provides geocoding based on OpenStreetMap data. It uses a PostgreSQL
database as a backend for storing the data.
There are three basic parts to Nominatim's architecture: the data import,
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/pqSQL via database triggers
+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`.
-The __search frontend__ implements the actual API. It takes queries for
-search and reverse geocoding queries from the user, looks up the data and
+The __search frontend__ implements the actual API. It takes search
+and reverse geocoding queries from the user, looks up the data and
returns the results in the requested format. This part is written in PHP
and can be found in the `lib/` and `website/` directories.
projects / nominatim.git / commitdiff