berlinplaces

README

berlinplaces

REST-Service for autocompletion and geocoding of places and addresses in Berlin.

berlinplaces is essentially me playing around with Open Street Map data. The goal is (was), to imitate Google's Places Autocomplete (-API) without the strings attached. That is, provide an API that is free (beer and speech), has a low latency, has a good "hit rate" (e.g. compensates typos), and is slim and easy in terms of deployment.

Thus here it is, berlinplaces is:

• free: it's here and OSS
• latency: basic tests show ~200µs without typos and ~12ms with early typos (if completed first time)
• hit rate: berlinplaces uses lookup tables for speed and Levenshtein for typos
• slim and easy: 35MB Docker image (incl. (REST-) server, OSM-data (!), swagger-docs and demo website)

The demo (see below) looks like:

Getting Started

Getting Sources

First, clone the repo and switch into the new directory:

git clone git@github.com:heimdalr/berlinplaces.git
cd berlinplaces

Build and Run

Inside the directory (berlinplaces), build and run via Docker:

docker build -t berlinplaces .
docker run -p 8080:8080 -e PLACES_DEBUG=true --name berlinplaces berlinplaces

or have Go >= 1.17 installed and run:

go build -o berlinplaces .
./berlinplaces 

API Usage

After the service is up and running (via docker or local), run (e.g.):

curl --request GET --url 'http://localhost:8080/places?text=Tiergartenq' | jq

which will result in something like:

[
  {
    "distance": 4,
    "place": {
      "id": 10561,
      "class": "street",
      "name": "Tiergartenufer",
      "postcode": "10623",
      "district": "Charlottenburg-Wilmersdorf",
      "length": 236,
      "lat": 52.513022715666686,
      "lon": 13.333934396722077,
      "relevance": 3
    }
  },
  {
    "distance": 5,
    "place": {
      "id": 13969,
      "class": "location",
      "type": "restaurant",
      "name": "Tiergartenquelle",
      "street": "Bachstraße",
      "streetID": 1012,
      "houseNumber": "6",
      "postcode": "10555",
      "district": "Mitte",
      "lat": 52.5151591,
      "lon": 13.3367789,
      "relevance": 0
    }
  }
]

The API spec is thereby served at http://localhost:8080/swagger.

Note, whether the API spec is being served is controlled via the environment variable PLACES_SPEC (and defaults depend on PLACES_DEBUG).

DEMO

To see a demo website using the API for a location / address input, surf to http://localhost:8080/demo.

Note, whether the demo website is being served is controlled via the environment variable PLACES_DEMO (and defaults depend on PLACES_DEBUG).

OSM Data

The repository at hand contains "mangled" OSM data for Berlin (_data/*.csv) - hence berlinplaces.

See _data/README.md for how to generate those CSV files.