Address

Self-hosted real-address generator backed by official registries and open map data for 27 countries and regions

English · 简体中文 · 繁體中文

Overview

Address returns addresses that actually exist instead of randomly assembled strings. Every record comes from an official address register, open map data, or a validated geocoding result, and carries its source, precision, and coordinates. Missing fields stay empty; nothing is invented.

Use it for form and checkout testing, address-format validation, logistics demos, and anywhere an address must look real and be real.

Features

• 27 countries and regions – Region, city, district, and postcode filters that follow each country's real administrative hierarchy. A filter with no data returns an error instead of silently switching to another area.
• Traceable sources – Residential communities for China; premise- and street-level addresses elsewhere, labelled with precision and residential evidence.
• Ten display languages – Native, English, Simplified and Traditional Chinese, Japanese, Korean, German, French, Spanish, and Portuguese.
• Hands-off synchronization – Incremental imports with bounded retries, exponential backoff, quota waits, and source-exhaustion detection, so failing work is never repeated forever.
• Admin console – Dashboard, country workspace, sync history, quick locations, provider credentials, translation routing, access control, and API tokens.
• Open API – Bearer-authenticated JSON API for single and batch generation, location search, coverage, and address translation, with an OpenAPI 3.1 document.
• Single-file deployment – One Docker Compose file runs the app, PostgreSQL, migrations, and the sync service; internal secrets are generated and persisted automatically.

Quick start

Requirements

• Linux (AMD64 or ARM64)
• Docker Engine 24+ with Docker Compose v2
• 4 GB RAM (8 GB or more recommended for the first import of large countries)

Deploy with Docker Compose

# 1. Create a deployment directory and download the Compose file
mkdir address && cd address
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/daimon3332/address/main/docker-compose.yml

# 2. Start all services
docker compose up -d

# 3. Check readiness
docker compose ps
curl -fsS http://127.0.0.1:8787/api/v1/ready

On first start the stack:

• creates persistent data/ and runtime/ directories next to the Compose file;
• generates the database password, configuration encryption key, and service tokens in data/secrets/;
• runs database migrations, then starts the API and the sync service.

First sign-in

1. Open http://127.0.0.1:8787/admin/ and sign in with the initial password admin.
2. Change the administrator password when prompted.
3. Decide under Access & Security whether the public generator needs a password.
4. Create an API token under API Tokens for external clients.

To start with your own password, set ADMIN_INITIAL_PASSWORD before the first docker compose up -d.

Go public

The API listens on 127.0.0.1:8787 only. Put it behind an HTTPS reverse proxy and create a .env next to the Compose file:

ALLOWED_ORIGINS=https://address.example.com
TRUST_PROXY=true
COOKIE_SECURE=true

See the deployment guide for Nginx and Caddy examples, upgrades, backups, and restores.

Usage

Web

Open http://127.0.0.1:8787/, pick a country, area, and display language, and generate. Results can be copied, exported, saved to favorites, or opened in Google Maps or AMap.

API

curl -fsS "http://127.0.0.1:8787/api/v1/generate?country=US&city=Seattle" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "country": "US",
    "filters": { "city": "Seattle" },
    "filterMatchLevel": "exact",
    "result": {
      "address": {
        "formattedAddress": "4019 Aikins Avenue Southwest, Seattle, WA, 98116",
        "matchLevel": "premise",
        "propertyType": "residential",
        "coordinates": { "latitude": 47.567944, "longitude": -122.40706 }
      }
    }
  }
}

The response is abridged. matchLevel is the address precision (street, premise, or subpremise); propertyType is residential only when independent residential evidence exists. See the API reference for every endpoint, parameter, and error code.

Provider keys (optional)

The service runs without any third-party key, using open sources that need no authorization. China map platforms, Google Geocoding, and translation services only extend data for specific countries or enable online translation; add them under Map Keys in the admin console. See API keys for how to obtain each one.

This is the beginning of the README. Read the rest at the original. Read the full README ↗