Administrator’s guide

Administrator’s guide


Table of Contents
< All Topics


Some runtime parameters, like the API port, the filename of the location database etc. are configurable.

To determine the value of an option, the following logic is applied:

  • If a System property with the name swiftflow.<configkey> (e.g. swiftflow.serverPort) exists, this value is selected. Example: java -Dswiftflow.serverPort=8080 -jar /.../swiftflow-api.jar
  • Otherwise, the setting is looked for in the configuration file (if the file exists). The default location for the configuration file is $HOME/swiftflow.conf, but it can also be overridden by specifying the swiftflow.configurationFile system property. The configuration file is an extremely simple key=value format, example: serverPort=8081. Note that keys in the configuration file are NOT prefixed with swiftflow. Empty lines and comment lines (starting with #) are ignored.
  • Finally, if neither a system property nor a configuration file entry are found, the default value is used.

Standard configuration keys

Here is a list of supported configuration keys, along with a short description and the default settings.

  • configurationFile: the file to be used to look for configuration items, as explained above. Default: $HOME/swiftflow.conf
  • serverPort: TCP Port that the HTTP API will listen on; note that the host is hard-coded to Default: 9000
  • locationDb: Full path to the SQLite database containing City-country mappings etc. Default: /swiftflow-data/locations.db
  • nominatimUrl: Full URL to a usable Nominatim backend. There is no default value, but an example would be: While it is technically possible to use the public URL, this should only ever be used for very limited tests, as using it in production is against the TOS of Nominatim and OSM.
  • licenseFile: Path to the swiftflow license file (both absolute and relative paths are OK). Default: swiftflow.license

Advanced configuration keys

The following settings modify the behavior of the system. It is not recommended to change them.

  • geoLookupExpandAddresses: (true/false) — determines whether geolookup logic should use JPostal logic to “expand” addresses into alternatives (e.g. by expanding common abbreviations like “St” to “Street”, province or region codes etc.). Default: true
  • geoLookupParseAddresses: (true/false) — determines whether geolookup logic should use JPostal logic to parse addresses, i.e., try to determine the parts (street, zipcode, city, …) the address is made of. Default: true
  • geoLookupBroadenQueries: (true/false) — determines whether geolookup logic, while querying the Nominatim backend, should retry with a “broader” query (containing fewer components) if no results are found. This will successively drop parts which are considered less important (e.g. street number first, then city, then region, etc.). Only applicable if geoLookupParseAddresses is enabled, as it depends on parsing to determine the order of components. Default: true
  • geoLookupEnableLocalDB: (true/false) — determines whether geolookup logic should employ the local SQLite DB, e.g. for determining countries from city names. Automatically disabled if geoLookupParseAddresses is disabled. Default: true