rezaq/libpostal-rest repository overview

⁠rezaq/libpostal-rest

A lightweight REST API wrapper around libpostal, built on top of rezaq/libpostal.

This image downloads the libpostal model automatically on first run and exposes easy-to-use HTTP endpoints for address parsing and expansion.

Perfect for microservices, data pipelines, ETL jobs, and applications that can't embed native libpostal.

⁠🚀 Features

• 🌐 REST API for parsing & expanding addresses
• ⚡ Fast & stateless – scales horizontally
• 📦 Small image – model downloaded dynamically
• 🧩 Parametric model selection with MODEL=...
• 💾 Volume persistence recommended for /data
• 🚀 Multi-arch: amd64 & arm64

⁠📦 First Run & Dataset Download

On startup, the container checks /data.
If the selected model is missing, it automatically downloads it.

Example:

docker run -d \
  -p 8080:8080 \
  -v /path/to/folder:/data \
  rezaq/libpostal-rest:latest

⁠🧰 Parametric Model Management

By default, the libpostal model is used.You can override it with Senzing model which is performing better.

docker run -it \
  -e MODEL=senzing \
  -v /path/to/folder:/data \
  rezaq/libpostal-rest:latest

The startup script detects whether the correct model already exists in /data. If not, it downloads and initializes it automatically.

⁠More Info

GitHub page⁠ REST API source⁠