Set up your own geocoder API with Docker

calendar 20-3-2023 · 3 min read · Geo Docker  ·
Share on: linkedin copy

For one of my projects I need an API for autocomplete geographical data. So for example, when someone types "27th street lo" that it returns "27th Street, Long Island, New York" in a formatted way including the geographical location.

Google and other service providers, provide these kinds of APIs. But in the end, they come with a cost per request. In this era, nothing is easier than run it on your own. You need some Docker knowledge, but if you have, you can have a geocoder API running in less than 10 minutes.

In this blog post I will explain how you set up a geocoder API based on Open Street Map data using Docker. I will explain every step. And I assure you, that it is easy to do.

Ok, let's go. Some info:

A. Get the necessary sources

I have added a project to GitHub

  1. Clone this Photon Github project: git clone https://github.com/tonsnoei/photon-docker

B. (Optional) Build your own docker image

You can skip this step. But if, in the future, the used docker image is lost for some reason. You can build it yourself:

  1. Create a docker hub account at the Docker Hub website
  2. Go to the directory where the clone is placed and run the following commands:
  3. (Optional) Open the Dockerfile and check the photon.jar file version that is used.
  4. (Optional) Check the available latest release here https://github.com/komoot/photon/releases/ and change the Dockerfile accordingly
  5. Build the docker image of Photon API docker build -t <DOCKER HUB USERNAME>/docker-photon:latest -f Dockerfile .
  6. Push the docker image to the docker hub: docker push <DOCKER HUB USERNAME>/docker-photon:latest
  7. Change the docker-compose.yml file to use this new docker image:
 1version: '2'
 2services:
 3  photon:
 4    build:
 5      context: .
 6      dockerfile: Dockerfile
 7>>> image: tonsnoei/photon-geocoder:latest
 8    volumes:
 9      - data:/photon/photon_data
10    ports:
11      - 2322:2322
12
13volumes:
14  data:
15    driver: local

C. Prepare your docker

  1. Be sure you are in the directory where https://github.com/tonsnoei/photon-docker is cloned.
  2. Create a directory "data": mkdir data
  3. By default, the whole world is available within the API. This means that you need a relatively heavy server. This means at least 4 cores with at least 16Gb of RAM.
  4. If you want to host just a single country, you can modify the entrypoint.sh file to use a country extract only. Extracts can be found here. The explanation of changing the entrypoint.sh can be found within the entrypoint.sh file
  5. Run: docker-compose build. This will rebuild the contents of the Dockerfile. This is especially important when you made changes to the entrypoint.sh.
  6. Now you are all set, run: docker-compose up -d && docker-compose logs -f
  7. It will now start with downloading the extract from the web as first step.
  8. If you stop de docker container while downloading the data half way, clear the data directory first before continuing.
  9. After the extract is downloaded, the API will be available at http://localhost:2322/api?q=amsterdam
  10. If you want to use a different region extract:
    1. Turn off the docker docker-compose down
    2. Modify the entrypoint.sh file
    3. Run docker-compose build
    4. Run docker-compose up -d && docker-compose logs -f

To run this on a production environment, use a reverse proxy like Nginx or Traefik to handle the HTTP(S) traffic.

That's it. Have fun.

Translations: