diff --git a/.github/actions/build-nominatim/action.yml b/.github/actions/build-nominatim/action.yml index d0a89774..191ef2ee 100644 --- a/.github/actions/build-nominatim/action.yml +++ b/.github/actions/build-nominatim/action.yml @@ -6,7 +6,7 @@ runs: steps: - name: Install prerequisites run: | - sudo apt-get install -y -qq libboost-system-dev libboost-filesystem-dev libexpat1-dev zlib1g-dev libbz2-dev libpq-dev libproj-dev libicu-dev python3-psycopg2 python3-pyosmium python3-dotenv python3-psutil python3-jinja2 python3-icu + sudo apt-get install -y -qq libboost-system-dev libboost-filesystem-dev libexpat1-dev zlib1g-dev libbz2-dev libpq-dev libproj-dev libicu-dev python3-psycopg2 python3-pyosmium python3-dotenv python3-psutil python3-jinja2 python3-icu python3-argparse-manpage shell: bash - name: Download dependencies diff --git a/CMakeLists.txt b/CMakeLists.txt index 1c6336a4..6ac81c4f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -36,6 +36,7 @@ set(BUILD_API on CACHE BOOL "Build everything for the API server") set(BUILD_MODULE on CACHE BOOL "Build PostgreSQL module") set(BUILD_TESTS on CACHE BOOL "Build test suite") set(BUILD_DOCS on CACHE BOOL "Build documentation") +set(BUILD_MANPAGE on CACHE BOOL "Build Manual Page") set(BUILD_OSM2PGSQL on CACHE BOOL "Build osm2pgsql (expert only)") #----------------------------------------------------------------------------- @@ -208,6 +209,14 @@ if (BUILD_DOCS) add_subdirectory(docs) endif() +#----------------------------------------------------------------------------- +# Manual page +#----------------------------------------------------------------------------- + +if (BUILD_MANPAGE) + add_subdirectory(manual) +endif() + #----------------------------------------------------------------------------- # Installation #----------------------------------------------------------------------------- diff --git a/manual/CMakeLists.txt b/manual/CMakeLists.txt new file mode 100644 index 00000000..9b69b790 --- /dev/null +++ b/manual/CMakeLists.txt @@ -0,0 +1,15 @@ +# Creates and installs manual page + +configure_file(${PROJECT_SOURCE_DIR}/manual/create-manpage.tmpl create_manpage.py) + +find_program(ARGPARSEMANPAGE argparse-manpage) + +ADD_CUSTOM_TARGET(manpage + COMMAND ${ARGPARSEMANPAGE} --pyfile ${CMAKE_CURRENT_BINARY_DIR}/create_manpage.py + --function get_parser --project-name Nominatim + --url https://nominatim.org > ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1 + + COMMAND sed -i '/.SH AUTHORS/I,+2 d' ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1 +) + +install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1 DESTINATION share/man/man1 ) diff --git a/manual/create-manpage.tmpl b/manual/create-manpage.tmpl new file mode 100644 index 00000000..34f00a8b --- /dev/null +++ b/manual/create-manpage.tmpl @@ -0,0 +1,12 @@ +#!/usr/bin/env python3 +import sys +import os + +sys.path.append('@PROJECT_SOURCE_DIR@') + +from nominatim.cli import get_set_parser + +def get_parser(): + parser = get_set_parser(phpcgi_path='@PHPCGI_BIN@') + + return parser.parser diff --git a/manual/nominatim.1 b/manual/nominatim.1 new file mode 100644 index 00000000..c5563bb5 --- /dev/null +++ b/manual/nominatim.1 @@ -0,0 +1,1015 @@ +.TH nominatim "1" Manual +.SH NAME +nominatim +.SH SYNOPSIS +.B nominatim +[-h] {import,freeze,replication,special-phrases,add-data,index,refresh,admin,export,serve,search,reverse,lookup,details,status,transition} ... +.SH DESCRIPTION + Command\-line tools for importing, updating, administrating and + querying the Nominatim database. + +.SH OPTIONS + + +.SS +\fBSub-commands\fR +.TP +\fBnominatim\fR \fI\,import\/\fR + Create a new Nominatim database from an OSM file. +.TP +\fBnominatim\fR \fI\,freeze\/\fR + Make database read-only. +.TP +\fBnominatim\fR \fI\,replication\/\fR + Update the database using an online replication service. +.TP +\fBnominatim\fR \fI\,special-phrases\/\fR + Import special phrases. +.TP +\fBnominatim\fR \fI\,add-data\/\fR + Add additional data from a file or an online source. +.TP +\fBnominatim\fR \fI\,index\/\fR + Reindex all new and modified data. +.TP +\fBnominatim\fR \fI\,refresh\/\fR + Recompute auxiliary data used by the indexing process. +.TP +\fBnominatim\fR \fI\,admin\/\fR + Analyse and maintain the database. +.TP +\fBnominatim\fR \fI\,export\/\fR + Export addresses as CSV file from the database. +.TP +\fBnominatim\fR \fI\,serve\/\fR + Start a simple web server for serving the API. +.TP +\fBnominatim\fR \fI\,search\/\fR + Execute API search query. +.TP +\fBnominatim\fR \fI\,reverse\/\fR + Execute API reverse query. +.TP +\fBnominatim\fR \fI\,lookup\/\fR + Execute API lookup query. +.TP +\fBnominatim\fR \fI\,details\/\fR + Execute API details query. +.TP +\fBnominatim\fR \fI\,status\/\fR + Execute API status query. +.TP +\fBnominatim\fR \fI\,transition\/\fR + Internal functions for code transition. Do not use. +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-osm\-file\fR FILE +OSM file to be imported. + +.TP +\fB\-\-continue\fR {load\-data,indexing,db\-postprocess} +Continue an import that was interrupted + +.TP +\fB\-\-osm2pgsql\-cache\fR SIZE +Size of cache to be used by osm2pgsql (in MB) + +.TP +\fB\-\-reverse\-only\fR +Do not create tables and indexes for searching + +.TP +\fB\-\-no\-partitions\fR +Do not partition search indices (speeds up import of single country extracts) + +.TP +\fB\-\-no\-updates\fR +Do not keep tables that are only needed for updating the database later + +.TP +\fB\-\-ignore\-errors\fR +Continue import even when errors in SQL are present + +.TP +\fB\-\-index\-noanalyse\fR +Do not perform analyse operations during index + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-init\fR +Initialise the update process + +.TP +\fB\-\-no\-update\-functions\fR +Do not update the trigger function to support differential updates. + +.TP +\fB\-\-check\-for\-updates\fR +Check if new updates are available and exit + +.TP +\fB\-\-once\fR +Download and apply updates only once. When not set, updates are continuously applied + +.TP +\fB\-\-no\-index\fR +Do not index the new data. Only applicable together with \-\-once + +.TP +\fB\-\-osm2pgsql\-cache\fR SIZE +Size of cache to be used by osm2pgsql (in MB) + +.TP +\fB\-\-socket\-timeout\fR \fI\,SOCKET_TIMEOUT\/\fR +Set timeout for file downloads. + +.SH OPTIONS 'nominatim special-phrases' +usage: nominatim special-phrases [-h] [-q] [-v] [--project-dir DIR] [-j NUM] + [--import-from-wiki] + + Import special phrases. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-import\-from\-wiki\fR +Import special phrases from the OSM wiki to the database. + +.SH 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] + + Add additional data from a file or an online source. + + Data is only imported, not indexed. You need to call `nominatim\-update index` + to complete the process. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-file\fR FILE +Import data from an OSM file + +.TP +\fB\-\-diff\fR FILE +Import data from an OSM diff file + +.TP +\fB\-\-node\fR ID +Import a single node from the API + +.TP +\fB\-\-way\fR ID +Import a single way from the API + +.TP +\fB\-\-relation\fR ID +Import a single relation from the API + +.TP +\fB\-\-tiger\-data\fR DIR +Add housenumbers from the US TIGER census database. + +.TP +\fB\-\-use\-main\-api\fR +Use OSM API instead of Overpass to download objects + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-boundaries\-only\fR +Index only administrative boundaries. + +.TP +\fB\-\-no\-boundaries\fR +Index everything except administrative boundaries. + +.TP +\fB\-\-minrank\fR RANK, \fB\-r\fR RANK +Minimum/starting rank + +.TP +\fB\-\-maxrank\fR RANK, \fB\-R\fR RANK +Maximum/finishing rank + +.SH 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. + + These functions must not be run in parallel with other update commands. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-postcodes\fR +Update postcode centroid table + +.TP +\fB\-\-word\-counts\fR +Compute frequency of full\-word search terms + +.TP +\fB\-\-address\-levels\fR +Reimport address level configuration + +.TP +\fB\-\-functions\fR +Update the PL/pgSQL functions in the database + +.TP +\fB\-\-wiki\-data\fR +Update Wikipedia/data importance numbers. + +.TP +\fB\-\-importance\fR +Recompute place importances (expensive!) + +.TP +\fB\-\-website\fR +Refresh the directory that serves the scripts for the web API + +.TP +\fB\-\-no\-diff\-updates\fR +Do not enable code for propagating updates + +.TP +\fB\-\-enable\-debug\-statements\fR +Enable debug warning statements in functions + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-warm\fR +Warm database caches for search and reverse queries. + +.TP +\fB\-\-check\-database\fR +Check that the database is complete and operational. + +.TP +\fB\-\-migrate\fR +Migrate the database to a new software version. + +.TP +\fB\-\-analyse\-indexing\fR +Print performance analysis of the indexing process. + +.TP +\fB\-\-search\-only\fR +Only pre\-warm tables for search queries + +.TP +\fB\-\-reverse\-only\fR +Only pre\-warm tables for reverse queries + +.TP +\fB\-\-osm\-id\fR \fI\,OSM_ID\/\fR +Analyse indexing of the given OSM object + +.TP +\fB\-\-place\-id\fR \fI\,PLACE_ID\/\fR +Analyse indexing of the given Nominatim object + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-output\-type\fR {continent,country,state,county,city,suburb,street,path} +Type of places to output (default: street) + +.TP +\fB\-\-output\-format\fR \fI\,OUTPUT_FORMAT\/\fR +Semicolon\-separated list of address types (see \-\-output\-type). Multiple ranks can be merged into one column by simply using a comma\-separated list. + +.TP +\fB\-\-output\-all\-postcodes\fR +List all postcodes for address instead of just the most likely one + +.TP +\fB\-\-language\fR \fI\,LANGUAGE\/\fR +Preferred language for output (use local name, if omitted) + +.TP +\fB\-\-restrict\-to\-country\fR COUNTRY_CODE +Export only objects within country + +.TP +\fB\-\-restrict\-to\-osm\-node\fR ID +Export only children of this OSM node + +.TP +\fB\-\-restrict\-to\-osm\-way\fR ID +Export only children of this OSM way + +.TP +\fB\-\-restrict\-to\-osm\-relation\fR ID +Export only children of this OSM relation + +.SH 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 develop. Do not use it in production setups! + + By the default, the webserver can be accessed at: http://127.0.0.1:8088 + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-server\fR \fI\,SERVER\/\fR +The address the server will listen to. + +.SH 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 API search query. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-query\fR \fI\,QUERY\/\fR +Free\-form query string + +.TP +\fB\-\-street\fR \fI\,STREET\/\fR +Structured query: housenumber and street + +.TP +\fB\-\-city\fR \fI\,CITY\/\fR +Structured query: city, town or village + +.TP +\fB\-\-county\fR \fI\,COUNTY\/\fR +Structured query: county + +.TP +\fB\-\-state\fR \fI\,STATE\/\fR +Structured query: state + +.TP +\fB\-\-country\fR \fI\,COUNTRY\/\fR +Structured query: country + +.TP +\fB\-\-postalcode\fR \fI\,POSTALCODE\/\fR +Structured query: postcode + +.TP +\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson} +Format of result + +.TP +\fB\-\-addressdetails\fR +Include a breakdown of the address into elements. + +.TP +\fB\-\-extratags\fR +Include additional information if available (e.g. wikipedia link, opening hours). + +.TP +\fB\-\-namedetails\fR +Include a list of alternative names. + +.TP +\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS +Preferred language order for presenting search results + +.TP +\fB\-\-polygon\-output\fR {geojson,kml,svg,text} +Output geometry of results as a GeoJSON, KML, SVG or WKT. + +.TP +\fB\-\-polygon\-threshold\fR TOLERANCE +Simplify output geometry.Parameter is difference tolerance in degrees. + +.TP +\fB\-\-countrycodes\fR CC,.. +Limit search results to one or more countries. + +.TP +\fB\-\-exclude_place_ids\fR ID,.. +List of search object to be excluded + +.TP +\fB\-\-limit\fR \fI\,LIMIT\/\fR +Limit the number of returned results + +.TP +\fB\-\-viewbox\fR X1,Y1,X2,Y2 +Preferred area to find search results + +.TP +\fB\-\-bounded\fR +Strictly restrict results to viewbox area + +.TP +\fB\-\-no\-dedupe\fR +Do not remove duplicates from the result list + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-lat\fR \fI\,LAT\/\fR +Latitude of coordinate to look up (in WGS84) + +.TP +\fB\-\-lon\fR \fI\,LON\/\fR +Longitude of coordinate to look up (in WGS84) + +.TP +\fB\-\-zoom\fR \fI\,ZOOM\/\fR +Level of detail required for the address + +.TP +\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson} +Format of result + +.TP +\fB\-\-addressdetails\fR +Include a breakdown of the address into elements. + +.TP +\fB\-\-extratags\fR +Include additional information if available (e.g. wikipedia link, opening hours). + +.TP +\fB\-\-namedetails\fR +Include a list of alternative names. + +.TP +\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS +Preferred language order for presenting search results + +.TP +\fB\-\-polygon\-output\fR {geojson,kml,svg,text} +Output geometry of results as a GeoJSON, KML, SVG or WKT. + +.TP +\fB\-\-polygon\-threshold\fR TOLERANCE +Simplify output geometry.Parameter is difference tolerance in degrees. + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-id\fR OSMID +OSM id to lookup in format (may be repeated) + +.TP +\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson} +Format of result + +.TP +\fB\-\-addressdetails\fR +Include a breakdown of the address into elements. + +.TP +\fB\-\-extratags\fR +Include additional information if available (e.g. wikipedia link, opening hours). + +.TP +\fB\-\-namedetails\fR +Include a list of alternative names. + +.TP +\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS +Preferred language order for presenting search results + +.TP +\fB\-\-polygon\-output\fR {geojson,kml,svg,text} +Output geometry of results as a GeoJSON, KML, SVG or WKT. + +.TP +\fB\-\-polygon\-threshold\fR TOLERANCE +Simplify output geometry.Parameter is difference tolerance in degrees. + +.SH 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. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-node\fR \fI\,NODE\/\fR, \fB\-n\fR \fI\,NODE\/\fR +Look up the OSM node with the given ID. + +.TP +\fB\-\-way\fR \fI\,WAY\/\fR, \fB\-w\fR \fI\,WAY\/\fR +Look up the OSM way with the given ID. + +.TP +\fB\-\-relation\fR \fI\,RELATION\/\fR, \fB\-r\fR \fI\,RELATION\/\fR +Look up the OSM relation with the given ID. + +.TP +\fB\-\-place_id\fR \fI\,PLACE_ID\/\fR, \fB\-p\fR \fI\,PLACE_ID\/\fR +Database internal identifier of the OSM object to look up. + +.TP +\fB\-\-class\fR \fI\,OBJECT_CLASS\/\fR +Class type to disambiguated multiple entries of the same object. + +.TP +\fB\-\-addressdetails\fR +Include a breakdown of the address into elements. + +.TP +\fB\-\-keywords\fR +Include a list of name keywords and address keywords. + +.TP +\fB\-\-linkedplaces\fR +Include a details of places that are linked with this one. + +.TP +\fB\-\-hierarchy\fR +Include details of places lower in the address hierarchy. + +.TP +\fB\-\-group_hierarchy\fR +Group the places by type. + +.TP +\fB\-\-polygon_geojson\fR +Include geometry of result. + +.TP +\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS +Preferred language order for presenting search results + +.SH OPTIONS 'nominatim status' +usage: nominatim status [-h] [-q] [-v] [--project-dir DIR] [-j NUM] + [--format {text,json}] + + Execute API status query. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-format\fR {text,json} +Format of result + +.SH OPTIONS 'nominatim transition' +usage: nominatim transition [-h] [-q] [-v] [--project-dir DIR] [-j NUM] + [--create-db] [--setup-db] [--import-data] + [--load-data] [--create-tables] + [--create-partition-tables] [--index] + [--create-search-indices] [--create-country-names] + [--no-partitions] [--osm-file FILE] [--drop] + [--osm2pgsql-cache SIZE] [--no-analyse] + [--ignore-errors] [--reverse-only] + [--tiger-data FILE] + + Internal functions for code transition. Do not use. + + + + +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Print only error messages + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Increase verboseness of output + +.TP +\fB\-\-project\-dir\fR DIR +Base directory of the Nominatim installation (default:.) + +.TP +\fB\-j\fR NUM, \fB\-\-threads\fR NUM +Number of parallel threads to use + +.TP +\fB\-\-create\-db\fR +Create nominatim db + +.TP +\fB\-\-setup\-db\fR +Build a blank nominatim db + +.TP +\fB\-\-import\-data\fR +Import a osm file + +.TP +\fB\-\-load\-data\fR +Copy data to live tables from import table + +.TP +\fB\-\-create\-tables\fR +Create main tables + +.TP +\fB\-\-create\-partition\-tables\fR +Create required partition tables + +.TP +\fB\-\-index\fR +Index the data + +.TP +\fB\-\-create\-search\-indices\fR +Create additional indices required for search and update + +.TP +\fB\-\-create\-country\-names\fR +Create search index for default country names. + +.TP +\fB\-\-no\-partitions\fR +Do not partition search indices + +.TP +\fB\-\-osm\-file\fR FILE +File to import + +.TP +\fB\-\-drop\fR +Drop tables needed for updates, making the database readonly + +.TP +\fB\-\-osm2pgsql\-cache\fR SIZE +Size of cache to be used by osm2pgsql (in MB) + +.TP +\fB\-\-no\-analyse\fR +Do not perform analyse operations during index + +.TP +\fB\-\-ignore\-errors\fR +Ignore certain erros on import. + +.TP +\fB\-\-reverse\-only\fR +Do not create search tables and indexes + +.TP +\fB\-\-tiger\-data\fR FILE +File to import + +.SH DISTRIBUTION +The latest version of Nominatim may be downloaded from +.UR https://nominatim.org +.UE diff --git a/nominatim/cli.py b/nominatim/cli.py index 0876d9a4..e162d1a6 100644 --- a/nominatim/cli.py +++ b/nominatim/cli.py @@ -179,16 +179,16 @@ class QueryExport: help='Type of places to output (default: street)') group.add_argument('--output-format', default='street;suburb;city;county;state;country', - help="""Semicolon-separated list of address types - (see --output-type). Multiple ranks can be - merged into one column by simply using a - comma-separated list.""") + help=("Semicolon-separated list of address types " + "(see --output-type). Multiple ranks can be " + "merged into one column by simply using a " + "comma-separated list.")) group.add_argument('--output-all-postcodes', action='store_true', - help="""List all postcodes for address instead of - just the most likely one""") + help=("List all postcodes for address instead of " + "just the most likely one")) group.add_argument('--language', - help="""Preferred language for output - (use local name, if omitted)""") + help=("Preferred language for output " + "(use local name, if omitted)")) group = parser.add_argument_group('Filter arguments') group.add_argument('--restrict-to-country', metavar='COUNTRY_CODE', help='Export only objects within country') @@ -242,11 +242,10 @@ class AdminServe: def run(args): run_php_server(args.server, args.project_dir / 'website') - -def nominatim(**kwargs): +def get_set_parser(**kwargs): """\ - Command-line tools for importing, updating, administrating and - querying the Nominatim database. + Initializes the parser and adds various subcommands for + nominatim cli. """ parser = CommandlineParser('nominatim', nominatim.__doc__) @@ -276,4 +275,14 @@ def nominatim(**kwargs): parser.add_subcommand('transition', clicmd.AdminTransition) + return parser + + +def nominatim(**kwargs): + """\ + Command-line tools for importing, updating, administrating and + querying the Nominatim database. + """ + parser = get_set_parser(**kwargs) + return parser.run(**kwargs) diff --git a/nominatim/clicmd/api.py b/nominatim/clicmd/api.py index 7185d97c..c3e869b8 100644 --- a/nominatim/clicmd/api.py +++ b/nominatim/clicmd/api.py @@ -21,8 +21,8 @@ STRUCTURED_QUERY = ( EXTRADATA_PARAMS = ( ('addressdetails', 'Include a breakdown of the address into elements.'), - ('extratags', """Include additional information if available - (e.g. wikipedia link, opening hours)."""), + ('extratags', ("Include additional information if available " + "(e.g. wikipedia link, opening hours).")), ('namedetails', 'Include a list of alternative names.') ) @@ -49,8 +49,8 @@ def _add_api_output_arguments(parser): choices=['geojson', 'kml', 'svg', 'text'], help='Output geometry of results as a GeoJSON, KML, SVG or WKT.') group.add_argument('--polygon-threshold', type=float, metavar='TOLERANCE', - help="""Simplify output geometry. - Parameter is difference tolerance in degrees.""") + help=("Simplify output geometry." + "Parameter is difference tolerance in degrees.")) class APISearch: @@ -205,8 +205,8 @@ class APIDetails: objs.add_argument('--place_id', '-p', type=int, help='Database internal identifier of the OSM object to look up.') group.add_argument('--class', dest='object_class', - help="""Class type to disambiguated multiple entries - of the same object.""") + help=("Class type to disambiguated multiple entries " + "of the same object.")) group = parser.add_argument_group('Output arguments') for name, desc in DETAILS_SWITCHES: diff --git a/nominatim/clicmd/replication.py b/nominatim/clicmd/replication.py index fc18945e..f9c5561a 100644 --- a/nominatim/clicmd/replication.py +++ b/nominatim/clicmd/replication.py @@ -29,17 +29,17 @@ class UpdateReplication: help='Initialise the update process') group.add_argument('--no-update-functions', dest='update_functions', action='store_false', - help="""Do not update the trigger function to - support differential updates.""") + help=("Do not update the trigger function to " + "support differential updates.")) group = parser.add_argument_group('Arguments for updates') group.add_argument('--check-for-updates', action='store_true', help='Check if new updates are available and exit') group.add_argument('--once', action='store_true', - help="""Download and apply updates only once. When - not set, updates are continuously applied""") + help=("Download and apply updates only once. When " + "not set, updates are continuously applied")) group.add_argument('--no-index', action='store_false', dest='do_index', - help="""Do not index the new data. Only applicable - together with --once""") + help=("Do not index the new data. Only applicable " + "together with --once")) group.add_argument('--osm2pgsql-cache', metavar='SIZE', type=int, help='Size of cache to be used by osm2pgsql (in MB)') group = parser.add_argument_group('Download parameters') diff --git a/nominatim/clicmd/setup.py b/nominatim/clicmd/setup.py index 056643aa..92d06943 100644 --- a/nominatim/clicmd/setup.py +++ b/nominatim/clicmd/setup.py @@ -39,11 +39,11 @@ class SetupAll: group.add_argument('--reverse-only', action='store_true', help='Do not create tables and indexes for searching') group.add_argument('--no-partitions', action='store_true', - help="""Do not partition search indices - (speeds up import of single country extracts)""") + help=("Do not partition search indices " + "(speeds up import of single country extracts)")) group.add_argument('--no-updates', action='store_true', - help="""Do not keep tables that are only needed for - updating the database later""") + help="Do not keep tables that are only needed for " + "updating the database later") group = parser.add_argument_group('Expert options') group.add_argument('--ignore-errors', action='store_true', help='Continue import even when errors in SQL are present') diff --git a/vagrant/Install-on-Centos-7.sh b/vagrant/Install-on-Centos-7.sh index 610bbb04..fae961f1 100755 --- a/vagrant/Install-on-Centos-7.sh +++ b/vagrant/Install-on-Centos-7.sh @@ -42,7 +42,7 @@ python3-pip python3-setuptools python3-devel \ expat-devel zlib-devel libicu-dev - pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU + pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU argparse-manpage # diff --git a/vagrant/Install-on-Centos-8.sh b/vagrant/Install-on-Centos-8.sh index 17d07aec..ac3a1b60 100755 --- a/vagrant/Install-on-Centos-8.sh +++ b/vagrant/Install-on-Centos-8.sh @@ -35,7 +35,7 @@ python3-pip python3-setuptools python3-devel \ expat-devel zlib-devel libicu-dev - pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU + pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU argparse-manpage # diff --git a/vagrant/Install-on-Ubuntu-18.sh b/vagrant/Install-on-Ubuntu-18.sh index b90da871..9fda122e 100755 --- a/vagrant/Install-on-Ubuntu-18.sh +++ b/vagrant/Install-on-Ubuntu-18.sh @@ -30,7 +30,8 @@ export DEBIAN_FRONTEND=noninteractive #DOCS: postgresql-server-dev-10 postgresql-10-postgis-2.4 \ postgresql-contrib-10 postgresql-10-postgis-scripts \ php php-pgsql php-intl libicu-dev python3-pip \ - python3-psycopg2 python3-psutil python3-jinja2 python3-icu git + python3-psycopg2 python3-psutil python3-jinja2 python3-icu git \ + python3-argparse-manpage # The python-dotenv package that comes with Ubuntu 18.04 is too old, so # install the latest version from pip: diff --git a/vagrant/Install-on-Ubuntu-20.sh b/vagrant/Install-on-Ubuntu-20.sh index d04f5796..292947d1 100755 --- a/vagrant/Install-on-Ubuntu-20.sh +++ b/vagrant/Install-on-Ubuntu-20.sh @@ -33,7 +33,8 @@ export DEBIAN_FRONTEND=noninteractive #DOCS: postgresql-server-dev-12 postgresql-12-postgis-3 \ postgresql-contrib-12 postgresql-12-postgis-3-scripts \ php php-pgsql php-intl libicu-dev python3-dotenv \ - python3-psycopg2 python3-psutil python3-jinja2 python3-icu git + python3-psycopg2 python3-psutil python3-jinja2 python3-icu git \ + python3-argparse-manpage # # System Configuration