nominatim(1)

NAME
nominatim

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

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 API 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.

nominatim transition
        Internal functions for code transition. Do not use.

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.

-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.

--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

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.

-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 applicable 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 special phrases.

-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.

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 index`
    to complete the process.

-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

--diff FILE
    Import data from an OSM diff 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

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.

-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.
    These functions must not be run in parallel with other update commands.

-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 develop. 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 API search query.

-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.

-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.

-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 <NRW><id> (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.

-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.

-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

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.

-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

--create-db
    Create nominatim db

--setup-db
    Build a blank nominatim db

--import-data
    Import a osm file

--load-data
    Copy data to live tables from import table

--create-tables
    Create main tables

--create-partition-tables
    Create required partition tables

--index
    Index the data

--create-search-indices
    Create additional indices required for search and update

--create-country-names
    Create search index for default country names.

--no-partitions
    Do not partition search indices

--osm-file FILE
    File to import

--drop
    Drop tables needed for updates, making the database readonly

--osm2pgsql-cache SIZE
    Size of cache to be used by osm2pgsql (in MB)

--no-analyse
    Do not perform analyse operations during index

--ignore-errors
    Ignore certain erros on import.

--reverse-only
    Do not create search tables and indexes

--tiger-data FILE
    File to import

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