Address

Self-hosted residential-address and synthetic test-profile generation backed by PostgreSQL.

English · 简体中文 · 繁體中文

Address reads a synchronized PostgreSQL address pool and returns a randomly selected eligible record together with a coherent synthetic profile. Public generation never downloads an upstream dataset or calls a map provider.

Highlights

• 27 configured countries and regions with country, administrative-area, city, district, and postcode filters where supported.
• Strict filter semantics: an empty matching pool returns an error instead of silently switching to another location.
• Fast database-backed random selection across the complete eligible scope; it does not repeatedly read the first rows.
• Source/native, English, Simplified Chinese, Traditional Chinese, Japanese, Korean, German, French, Spanish, and Portuguese presentation paths.
• Address and profile language choices persist independently in the browser; first use defaults to English.
• Popular administrative areas, popular cities, and special areas are configurable per country. The United States includes states without statewide sales tax.
• Public coverage monitor plus administrator dashboard, address-data rules, synchronization queue, quick-location editor, provider credentials, access control, blacklist, and API tokens.
• PostgreSQL-only runtime with pooled connections, transactional publication, indexed location search, and prebuilt random-address indexes.

Supported scope

Architecture

Astro static pages + React UI
             │
             ▼
       Hono Node.js API
        ├─ PostgreSQL address and control data
        ├─ in-memory random/filter indexes rebuilt from PostgreSQL
        └─ local formatting, profile generation, and optional translation

Synchronization supervisor
        ├─ resumable bulk/API adapters
        ├─ country-specific validation and residential evidence gates
        ├─ transactional PostgreSQL publication
        └─ coverage statistics and bounded queue state

Automated synchronization

A country is complete only when every enabled rule passes:

1. total eligible-record target;
2. lowest administrative-level coverage and per-node minimums;
3. level-1 and level-2 minimums where configured;
4. every explicit node override.

Reaching only the total target does not mark a country complete. Conversely, a source proven to be exhausted is kept visible as incomplete but removed from active work until its source/version fingerprint changes.

The queue applies bounded retries, exponential backoff, cooldown/quota reset times, no-progress latching, and suspension after repeated failures. It cannot run the same unchanged no-progress source indefinitely. China receives the highest automatic priority while it remains eligible.

Screenshots

Data monitor

Administrator console

Quick start

Requirements: Node.js 24+, Docker Compose, and enough disk space for the datasets you choose to import.

git clone https://github.com/daimon3332/address.git
cd address

cd ops/postgresql
POSTGRES_PASSWORD='REPLACE_WITH_A_STRONG_PASSWORD' docker compose up -d
cd ../..

cp .env.example .env
# Set POSTGRES_URL, CONFIG_MASTER_KEY, and ADMIN_BOOTSTRAP_PASSWORD in .env.
npm ci
npm run db:migrate
npm run build
npm start

The initial database contains schema only. Import only the countries and sources whose licenses, resource requirements, and strategy documents you have reviewed. Production deployment, service supervision, reverse proxy, backup, and restore procedures are in the deployment guide.

Configuration and API keys

• Copy .env.example; never commit .env.
• Provider keys are optional unless the selected synchronization strategy needs them.
• Multiple credentials rotate independently. A failing key is cooled down while another available key is tried; when all keys are unavailable, work waits for the earliest reset.
• Encrypted administrator credentials depend on a stable CONFIG_MASTER_KEY.
• Follow the dedicated API key configuration guide for official application links, variable names, restrictions, and rotation behavior.

Documentation

License

Project source code is licensed under MIT. Upstream datasets retain their own licenses and attribution requirements.