the42/bevaddressapi repository overview

Working Demos can be found here:

• Official Website⁠
• GitHub Preview⁠

A Websocket API to provide search functionality in Austria's Address register as published under http://www.bev.gv.at/portal/page?_pageid=713,2601271&_dad=portal&_schema=PORTAL⁠

This package relies on the workings of these other components:

• bevdockerdb, a PostGIS powered PostgreSQL installation with abbreviations and thesaurus dictionary for improved full text search;
  Github Project⁠
  Docker Hub⁠
• bevaddress-dataload⁠, a set of scripts to load data into the aforementioned PostGIS database.

⁠Installation

⁠Install locally using

go get github.com/the42/bevaddressapi

Local installation requires a working Golang environment⁠.

⁠Configuration and running

bevaddressapi accepts two environment variables for configuration:

PORT - the tcp port on which the websocket API will listen for incoming connections, defaults to 5000 if not set; SECPORT - the tcp port on which the websocket API will listen for incoming TLS connections; If not set or empty, the service is only served unencrypted; DATABASE_URL - a url defining the connection parameters to the database.

Currently only PostGIS is supported as the database backend. See the documentation⁠ on how to set this environment variable.

⁠Install using Docker

docker pull the42/bevaddressapi

Running

docker run -it --name bevadr -P -p 5000:5000 -e DATABASE_URL=postgres://<DB_username>:<DB_password>@<DB_host>:<DB_port>/bevaddress the42/bevaddressapi

Replace DB_.... wit the appropriate values to the Address-database⁠

In case your database server does not support SSl-encryption use

docker run -it --name bevadr -P -p 5000:5000 -e DATABASE_URL=postgres://<DB_username>:<DB_password>@<DB_host>:<DB_port>/bevaddress?sslmode=disable the42/bevaddressapi

⁠Usage

The fulltext search endpoint is exposed as a websocket and listens as following:

/ws/address/fts: A websocket endpoint for full text search.

Parameters:

• q (required): url-encoded string for full text search.

All further parameters are optional:

• autocomplete: when set to 0, queries have to match exactly, any other parameter value will result in a postfix wildcard match.
  Example: with autocomplete=0, the query 3500 Krems, Eisentürg will not return any results, whereas with autocomplete set to any other value but 0 (default), the query will match 3500 Krems, Eisentürgasse.
  Default: true

Filters:

• postcode: filter by zip-code (Postleitzahl). Partial match is supported by including the character %, eg. postcode=35% will match any zip code starting with 35..
• citycode: filter by Gemeindekennzahl⁠. Partial match is supported by including the character %.
• province: filter by province (Bundesland). The coding is according to https://de.wikipedia.org/wiki/ISO_3166-2:AT⁠ eg. Burgenland=1, Kärnten=2, ... .
• lat, lon: filter by latitude and longitude using WGS84 coordinates⁠. When used, both parameters have to be set.

Number of returned results:

• n: return up to n results. A hard limit is implemented which prevents bulk downloads bringing down the server.
  Default: 25