Getting Started

System requirements

With the following set of commands one can easily setup OSMNames in a matter of minutes. Prerequisites are a working installation of Docker along with Docker Compose.


In order to increase the speed of the processing, an SSD disk is recommended. It is also recommended to tweak the database settings to match the specficiations of your system.

Run OSMNames

To run OSMNames, follow these steps:

  1. Checkout source from GitHub

    git clone
  2. Specify the URL to the PBF file in the .env file


    Alternatively place a custom PBF file in the data/import directory and define it in the .env file


    If PBF_FILE is defined PBF_FILE_URL will be ignored.

  3. Now run OSMNames
    docker-compose run --rm osmnames

This command will:

  1. Initialize the database inside a docker container
  2. Download and import a wikipedia dump
  3. Download and process the specified PBF file
  4. Export the OSMNames data

The export files for example, switzerland_geonames.tsv.gz and switzerland_housenumbers.tsv.gz can be found in the export directory data/export.

A more detailed and technical overview can be found in the documentation about the Implementation.


The execution time is highly dependent from the size of the PBF file and the available hardware. More details about the performance can be found in the corresponding documentation.

Extracting countries

The TSV file from the planet export includes more than 21‘000‘000 entries. The current data export can be downloaded at If one is only interested in a specific country, download the file and extract the information with the following command:

awk -F $'\t' 'BEGIN {OFS = FS}{if (NR!=1) {if ($16 =="[country_code]")  {print}} else {print}}' planet-latest.tsv > countryExtract.tsv

where [country_code] needs to be replaced with the ISO-3166 2-letter country code.