nominatim(1) General Commands Manual nominatim(1) NAME nominatim SYNOPSIS nominatim [-h] {import,freeze,replication,special-phrases,add- data,index,refresh,admin,export,serve,search,reverse,lookup,details,status} ... DESCRIPTION Command-line tools for importing, updating, administrating and querying the Nominatim database. OPTIONS Sub-commands nominatim import Create a new Nominatim database from an OSM file. nominatim freeze Make database read-only. nominatim replication Update the database using an online replication service. nominatim special-phrases Import special phrases. nominatim add-data Add additional data from a file or an online source. nominatim index Reindex all new and modified data. nominatim refresh Recompute auxiliary data used by the indexing process. nominatim admin Analyse and maintain the database. nominatim export Export addresses as CSV file from the database. nominatim serve Start a simple web server for serving the API. nominatim search Execute a search query. nominatim reverse Execute API reverse query. nominatim lookup Execute API lookup query. nominatim details Execute API details query. nominatim status Execute API status query. OPTIONS 'nominatim import' 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. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --osm-file FILE OSM file to be imported (repeat for importing multiple files) --continue {load-data,indexing,db-postprocess} Continue an import that was interrupted --osm2pgsql-cache SIZE Size of cache to be used by osm2pgsql (in MB) --reverse-only Do not create tables and indexes for searching --no-partitions Do not partition search indices (speeds up import of single country extracts) --no-updates Do not keep tables that are only needed for updating the database later --ignore-errors Continue import even when errors in SQL are present --index-noanalyse Do not perform analyse operations during index (expert only) OPTIONS 'nominatim freeze' 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. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use OPTIONS 'nominatim replication' 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. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --init Initialise the update process --no-update-functions Do not update the trigger function to support differential updates. --check-for-updates Check if new updates are available and exit --once Download and apply updates only once. When not set, updates are continuously applied --no-index Do not index the new data. Only usable together with --once --osm2pgsql-cache SIZE Size of cache to be used by osm2pgsql (in MB) --socket-timeout SOCKET_TIMEOUT Set timeout for file downloads OPTIONS 'nominatim special-phrases' 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'. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --import-from-wiki Import special phrases from the OSM wiki to the database --import-from-csv FILE Import special phrases from a CSV file --no-replace Keep the old phrases and only add the new ones OPTIONS 'nominatim add-data' 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. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --file FILE Import data from an OSM file or diff file --diff FILE Import data from an OSM diff file (deprecated: use --file) --node ID Import a single node from the API --way ID Import a single way from the API --relation ID Import a single relation from the API --tiger-data DIR Add housenumbers from the US TIGER census database --use-main-api Use OSM API instead of Overpass to download objects --osm2pgsql-cache SIZE Size of cache to be used by osm2pgsql (in MB) --socket-timeout SOCKET_TIMEOUT Set timeout for file downloads OPTIONS 'nominatim index' 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. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --boundaries-only Index only administrative boundaries. --no-boundaries Index everything except administrative boundaries. --minrank RANK, -r RANK Minimum/starting rank --maxrank RANK, -R RANK Maximum/finishing rank OPTIONS 'nominatim refresh' 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'. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --postcodes Update postcode centroid table --word-counts Compute frequency of full-word search terms --address-levels Reimport address level configuration --functions Update the PL/pgSQL functions in the database --wiki-data Update Wikipedia/data importance numbers --importance Recompute place importances (expensive!) --website Refresh the directory that serves the scripts for the web API --no-diff-updates Do not enable code for propagating updates --enable-debug-statements Enable debug warning statements in functions OPTIONS 'nominatim admin' 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. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --warm Warm database caches for search and reverse queries --check-database Check that the database is complete and operational --migrate Migrate the database to a new software version --analyse-indexing Print performance analysis of the indexing process --search-only Only pre-warm tables for search queries --reverse-only Only pre-warm tables for reverse queries --osm-id OSM_ID Analyse indexing of the given OSM object --place-id PLACE_ID Analyse indexing of the given Nominatim object OPTIONS 'nominatim export' 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. -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --output-type {continent,country,state,county,city,suburb,street,path} Type of places to output (default: street) --output-format OUTPUT_FORMAT Semicolon-separated list of address types (see --output-type). Multiple ranks can be merged into one column by simply using a comma-separated list. --output-all-postcodes List all postcodes for address instead of just the most likely one --language LANGUAGE Preferred language for output (use local name, if omitted) --restrict-to-country COUNTRY_CODE Export only objects within country --restrict-to-osm-node ID Export only children of this OSM node --restrict-to-osm-way ID Export only children of this OSM way --restrict-to-osm-relation ID Export only children of this OSM relation OPTIONS 'nominatim serve' 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 -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --server SERVER The address the server will listen to. OPTIONS 'nominatim search' 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/ -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --query QUERY Free-form query string --street STREET Structured query: housenumber and street --city CITY Structured query: city, town or village --county COUNTY Structured query: county --state STATE Structured query: state --country COUNTRY Structured query: country --postalcode POSTALCODE Structured query: postcode --format {xml,json,jsonv2,geojson,geocodejson} Format of result --addressdetails Include a breakdown of the address into elements --extratags Include additional information if available (e.g. wikipedia link, opening hours) --namedetails Include a list of alternative names --lang LANGS, --accept-language LANGS Preferred language order for presenting search results --polygon-output {geojson,kml,svg,text} Output geometry of results as a GeoJSON, KML, SVG or WKT --polygon-threshold TOLERANCE Simplify output geometry.Parameter is difference tolerance in degrees. --countrycodes CC,.. Limit search results to one or more countries --exclude_place_ids ID,.. List of search object to be excluded --limit LIMIT Limit the number of returned results --viewbox X1,Y1,X2,Y2 Preferred area to find search results --bounded Strictly restrict results to viewbox area --no-dedupe Do not remove duplicates from the result list OPTIONS 'nominatim reverse' 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/ -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --lat LAT Latitude of coordinate to look up (in WGS84) --lon LON Longitude of coordinate to look up (in WGS84) --zoom ZOOM Level of detail required for the address --format {xml,json,jsonv2,geojson,geocodejson} Format of result --addressdetails Include a breakdown of the address into elements --extratags Include additional information if available (e.g. wikipedia link, opening hours) --namedetails Include a list of alternative names --lang LANGS, --accept-language LANGS Preferred language order for presenting search results --polygon-output {geojson,kml,svg,text} Output geometry of results as a GeoJSON, KML, SVG or WKT --polygon-threshold TOLERANCE Simplify output geometry.Parameter is difference tolerance in degrees. OPTIONS 'nominatim lookup' 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/ -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --id OSMID OSM id to lookup in format (may be repeated) --format {xml,json,jsonv2,geojson,geocodejson} Format of result --addressdetails Include a breakdown of the address into elements --extratags Include additional information if available (e.g. wikipedia link, opening hours) --namedetails Include a list of alternative names --lang LANGS, --accept-language LANGS Preferred language order for presenting search results --polygon-output {geojson,kml,svg,text} Output geometry of results as a GeoJSON, KML, SVG or WKT --polygon-threshold TOLERANCE Simplify output geometry.Parameter is difference tolerance in degrees. OPTIONS 'nominatim details' 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/ -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --node NODE, -n NODE Look up the OSM node with the given ID. --way WAY, -w WAY Look up the OSM way with the given ID. --relation RELATION, -r RELATION Look up the OSM relation with the given ID. --place_id PLACE_ID, -p PLACE_ID Database internal identifier of the OSM object to look up --class OBJECT_CLASS Class type to disambiguated multiple entries of the same object. --addressdetails Include a breakdown of the address into elements --keywords Include a list of name keywords and address keywords --linkedplaces Include a details of places that are linked with this one --hierarchy Include details of places lower in the address hierarchy --group_hierarchy Group the places by type --polygon_geojson Include geometry of result --lang LANGS, --accept-language LANGS Preferred language order for presenting search results OPTIONS 'nominatim status' 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/ -q, --quiet Print only error messages -v, --verbose Increase verboseness of output --project-dir DIR Base directory of the Nominatim installation (default:.) -j NUM, --threads NUM Number of parallel threads to use --format {text,json} Format of result AUTHORS Nominatim was written by the Nominatim developer community . DISTRIBUTION The latest version of Nominatim may be downloaded from Manual nominatim(1)