nominatim(1) General Commands Manual nominatim(1)

nominatim

nominatim [-h] {import,freeze,replication,special-phrases,add-data,index,refresh,admin,export,serve,search,reverse,lookup,details,status} ...


Command-line tools for importing, updating, administrating and
querying the Nominatim database.

Sub-commands


Create a new Nominatim database from an OSM file.

Make database read-only.

Update the database using an online replication service.

Import special phrases.

Add additional data from a file or an online source.

Reindex all new and modified data.

Recompute auxiliary data used by the indexing process.

Analyse and maintain the database.

Export addresses as CSV file from the database.

Start a simple web server for serving the API.

Execute a search query.

Execute API reverse query.

Execute API lookup query.

Execute API details query.

Execute API status query.

usage: nominatim import [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
(--osm-file FILE | --continue {load-data,indexing,db-postprocess})
[--osm2pgsql-cache SIZE] [--reverse-only]
[--no-partitions] [--no-updates] [--ignore-errors]
[--index-noanalyse]


Create a new Nominatim database from an OSM file.


This sub-command sets up a new Nominatim database from scratch starting
with creating a new database in Postgresql. The user running this command
needs superuser rights on the database.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
OSM file to be imported (repeat for importing multiple files)
Continue an import that was interrupted
Size of cache to be used by osm2pgsql (in MB)
Do not create tables and indexes for searching
Do not partition search indices (speeds up import of single country extracts)
Do not keep tables that are only needed for updating the database later
Continue import even when errors in SQL are present
Do not perform analyse operations during index (expert only)

usage: nominatim freeze [-h] [-q] [-v] [--project-dir DIR] [-j NUM]


Make database read-only.


About half of data in the Nominatim database is kept only to be able to
keep the data up-to-date with new changes made in OpenStreetMap. This
command drops all this data and only keeps the part needed for geocoding
itself.


This command has the same effect as the `--no-updates` option for imports.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use

usage: nominatim replication [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--init] [--no-update-functions]
[--check-for-updates] [--once] [--no-index]
[--osm2pgsql-cache SIZE]
[--socket-timeout SOCKET_TIMEOUT]


Update the database using an online replication service.


An OSM replication service is an online service that provides regular
updates (OSM diff files) for the planet or update they provide. The OSMF
provides the primary replication service for the full planet at
https://planet.osm.org/replication/ but there are other providers of
extracts of OSM data who provide such a service as well.


This sub-command allows to set up such a replication service and download
and import updates at regular intervals. You need to call '--init' once to
set up the process or whenever you change the replication configuration
parameters. Without any arguments, the sub-command will go into a loop and
continuously apply updates as they become available. Giving `--once` just
downloads and imports the next batch of updates.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Initialise the update process
Do not update the trigger function to support differential updates.
Check if new updates are available and exit
Download and apply updates only once. When not set, updates are continuously applied
Do not index the new data. Only usable together with --once
Size of cache to be used by osm2pgsql (in MB)
Set timeout for file downloads

usage: nominatim special-phrases [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--import-from-wiki] [--import-from-csv FILE]
[--no-replace]


Import special phrases.


Special phrases are search terms that narrow down the type of object
that should be searched. For example, you might want to search for
'Hotels in Barcelona'. The OSM wiki has a selection of special phrases
in many languages, which can be imported with this command.


You can also provide your own phrases in a CSV file. The file needs to have
the following five columns:
* phrase - the term expected for searching
* class - the OSM tag key of the object type
* type - the OSM tag value of the object type
* operator - the kind of search to be done (one of: in, near, name, -)
* plural - whether the term is a plural or not (Y/N)


An example file can be found in the Nominatim sources at
'test/testdb/full_en_phrases_test.csv'.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Import special phrases from the OSM wiki to the database
Import special phrases from a CSV file
Keep the old phrases and only add the new ones

usage: nominatim add-data [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
(--file FILE | --diff FILE | --node ID | --way ID | --relation ID | --tiger-data DIR)
[--use-main-api] [--osm2pgsql-cache SIZE]
[--socket-timeout SOCKET_TIMEOUT]


Add additional data from a file or an online source.


This command allows to add or update the search data in the database.
The data can come either from an OSM file or single OSM objects can
directly be downloaded from the OSM API. This function only loads the
data into the database. Afterwards it still needs to be integrated
in the search index. Use the `nominatim index` command for that.


The command can also be used to add external non-OSM data to the
database. At the moment the only supported format is TIGER housenumber
data. See the online documentation at
https://nominatim.org/release-docs/latest/admin/Import/#installing-tiger-housenumber-data-for-the-us
for more information.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Import data from an OSM file or diff file
Import data from an OSM diff file (deprecated: use --file)
Import a single node from the API
Import a single way from the API
Import a single relation from the API
Add housenumbers from the US TIGER census database
Use OSM API instead of Overpass to download objects
Size of cache to be used by osm2pgsql (in MB)
Set timeout for file downloads

usage: nominatim index [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--boundaries-only] [--no-boundaries] [--minrank RANK]
[--maxrank RANK]


Reindex all new and modified data.


Indexing is the process of computing the address and search terms for
the places in the database. Every time data is added or changed, indexing
needs to be run. Imports and replication updates automatically take care
of indexing. For other cases, this function allows to run indexing manually.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Index only administrative boundaries.
Index everything except administrative boundaries.
Minimum/starting rank
Maximum/finishing rank

usage: nominatim refresh [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--postcodes] [--word-counts] [--address-levels]
[--functions] [--wiki-data] [--importance]
[--website] [--no-diff-updates]
[--enable-debug-statements]


Recompute auxiliary data used by the indexing process.


This sub-commands updates various static data and functions in the database.
It usually needs to be run after changing various aspects of the
configuration. The configuration documentation will mention the exact
command to use in such case.


Warning: the 'update' command must not be run in parallel with other update
commands like 'replication' or 'add-data'.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Update postcode centroid table
Compute frequency of full-word search terms
Reimport address level configuration
Update the PL/pgSQL functions in the database
Update Wikipedia/data importance numbers
Recompute place importances (expensive!)
Refresh the directory that serves the scripts for the web API
Do not enable code for propagating updates
Enable debug warning statements in functions

usage: nominatim admin [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
(--warm | --check-database | --migrate | --analyse-indexing)
[--search-only] [--reverse-only]
[--osm-id OSM_ID | --place-id PLACE_ID]


Analyse and maintain the database.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Warm database caches for search and reverse queries
Check that the database is complete and operational
Migrate the database to a new software version
Print performance analysis of the indexing process
Only pre-warm tables for search queries
Only pre-warm tables for reverse queries
Analyse indexing of the given OSM object
Analyse indexing of the given Nominatim object

usage: nominatim export [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--output-type {continent,country,state,county,city,suburb,street,path}]
[--output-format OUTPUT_FORMAT]
[--output-all-postcodes] [--language LANGUAGE]
[--restrict-to-country COUNTRY_CODE]
[--restrict-to-osm-node ID] [--restrict-to-osm-way ID]
[--restrict-to-osm-relation ID]


Export addresses as CSV file from the database.

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Type of places to output (default: street)
Semicolon-separated list of address types (see --output-type). Multiple ranks can be merged into one column by simply using a comma-separated list.
List all postcodes for address instead of just the most likely one
Preferred language for output (use local name, if omitted)
Export only objects within country
Export only children of this OSM node
Export only children of this OSM way
Export only children of this OSM relation

usage: nominatim serve [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--server SERVER]


Start a simple web server for serving the API.


This command starts the built-in PHP webserver to serve the website
from the current project directory. This webserver is only suitable
for testing and development. Do not use it in production setups!


By the default, the webserver can be accessed at: http://127.0.0.1:8088

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
The address the server will listen to.

usage: nominatim search [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--query QUERY] [--street STREET] [--city CITY]
[--county COUNTY] [--state STATE] [--country COUNTRY]
[--postalcode POSTALCODE]
[--format {xml,json,jsonv2,geojson,geocodejson}]
[--addressdetails] [--extratags] [--namedetails]
[--lang LANGS]
[--polygon-output {geojson,kml,svg,text}]
[--polygon-threshold TOLERANCE] [--countrycodes CC,..]
[--exclude_place_ids ID,..] [--limit LIMIT]
[--viewbox X1,Y1,X2,Y2] [--bounded] [--no-dedupe]


Execute a search query.


This command works exactly the same as if calling the /search endpoint on
the web API. See the online documentation for more details on the
various parameters:
https://nominatim.org/release-docs/latest/api/Search/

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Free-form query string
Structured query: housenumber and street
Structured query: city, town or village
Structured query: county
Structured query: state
Structured query: country
Structured query: postcode
Format of result
Include a breakdown of the address into elements
Include additional information if available (e.g. wikipedia link, opening hours)
Include a list of alternative names
Preferred language order for presenting search results
Output geometry of results as a GeoJSON, KML, SVG or WKT
Simplify output geometry.Parameter is difference tolerance in degrees.
Limit search results to one or more countries
List of search object to be excluded
Limit the number of returned results
Preferred area to find search results
Strictly restrict results to viewbox area
Do not remove duplicates from the result list

usage: nominatim reverse [-h] [-q] [-v] [--project-dir DIR] [-j NUM] --lat LAT
--lon LON [--zoom ZOOM]
[--format {xml,json,jsonv2,geojson,geocodejson}]
[--addressdetails] [--extratags] [--namedetails]
[--lang LANGS]
[--polygon-output {geojson,kml,svg,text}]
[--polygon-threshold TOLERANCE]


Execute API reverse query.


This command works exactly the same as if calling the /reverse endpoint on
the web API. See the online documentation for more details on the
various parameters:
https://nominatim.org/release-docs/latest/api/Reverse/

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Latitude of coordinate to look up (in WGS84)
Longitude of coordinate to look up (in WGS84)
Level of detail required for the address
Format of result
Include a breakdown of the address into elements
Include additional information if available (e.g. wikipedia link, opening hours)
Include a list of alternative names
Preferred language order for presenting search results
Output geometry of results as a GeoJSON, KML, SVG or WKT
Simplify output geometry.Parameter is difference tolerance in degrees.

usage: nominatim lookup [-h] [-q] [-v] [--project-dir DIR] [-j NUM] --id OSMID
[--format {xml,json,jsonv2,geojson,geocodejson}]
[--addressdetails] [--extratags] [--namedetails]
[--lang LANGS]
[--polygon-output {geojson,kml,svg,text}]
[--polygon-threshold TOLERANCE]


Execute API lookup query.


This command works exactly the same as if calling the /lookup endpoint on
the web API. See the online documentation for more details on the
various parameters:
https://nominatim.org/release-docs/latest/api/Lookup/

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
OSM id to lookup in format <NRW><id> (may be repeated)
Format of result
Include a breakdown of the address into elements
Include additional information if available (e.g. wikipedia link, opening hours)
Include a list of alternative names
Preferred language order for presenting search results
Output geometry of results as a GeoJSON, KML, SVG or WKT
Simplify output geometry.Parameter is difference tolerance in degrees.

usage: nominatim details [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
(--node NODE | --way WAY | --relation RELATION | --place_id PLACE_ID)
[--class OBJECT_CLASS] [--addressdetails]
[--keywords] [--linkedplaces] [--hierarchy]
[--group_hierarchy] [--polygon_geojson]
[--lang LANGS]


Execute API details query.


This command works exactly the same as if calling the /details endpoint on
the web API. See the online documentation for more details on the
various parameters:
https://nominatim.org/release-docs/latest/api/Details/

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Look up the OSM node with the given ID.
Look up the OSM way with the given ID.
Look up the OSM relation with the given ID.
Database internal identifier of the OSM object to look up
Class type to disambiguated multiple entries of the same object.
Include a breakdown of the address into elements
Include a list of name keywords and address keywords
Include a details of places that are linked with this one
Include details of places lower in the address hierarchy
Group the places by type
Include geometry of result
Preferred language order for presenting search results

usage: nominatim status [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
[--format {text,json}]


Execute API status query.


This command works exactly the same as if calling the /status endpoint on
the web API. See the online documentation for more details on the
various parameters:
https://nominatim.org/release-docs/latest/api/Status/

Print only error messages
Increase verboseness of output
Base directory of the Nominatim installation (default:.)
Number of parallel threads to use
Format of result

Nominatim was written by the Nominatim developer community <info@nominatim.org>.

The latest version of Nominatim may be downloaded from https://nominatim.org

Manual