address README

The project's README from github.com/daimon3332/address. As one markdown file: README.md.

Address

Address

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

English · 简体中文 · 繁體中文

CI Docker Node.js PostgreSQL License Demo

Address generator

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

Quick start

Requirements

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:

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.

Screenshots

Admin · DashboardAdmin · Country workspace
Admin dashboard Country workspace
Country detailTranslation credential test
Country detail OpenAI-compatible credential test
Public coverage monitorUS address
Public coverage monitor US address

Supported countries and regions

Region Countries and regions
North America United States US, Canada CA, Mexico MX
Europe United Kingdom GB, Germany DE, France FR, Italy IT, Spain ES, Netherlands NL, Russia RU
East Asia China CN, Hong Kong HK, Taiwan TW, Japan JP, South Korea KR
Southeast Asia Singapore SG, Malaysia MY, Thailand TH, Philippines PH, Vietnam VN
South Asia India IN
Oceania Australia AU
Middle East Türkiye TR, Saudi Arabia SA
South America Brazil BR
Africa Nigeria NG, South Africa ZA

Sources, field provenance, and residential evidence per country are listed in the data sources document.

How it works

Browser ──► Astro + React pages
               │
               ▼
           Hono API ──► PostgreSQL (address pool, admin catalog, control data)
               │
               └─ prebuilt random/filter indexes, local formatting and translation

Sync service ──► official registers / OpenStreetMap / Overture / map platforms
               │  validates source, administrative area, language, coordinates
               ▼
           per-country transactional publish ──► PostgreSQL

A country is complete only when three rules hold at once: the valid-address total, the lowest-level administrative coverage, and the per-level node minimums. When a source is proven to have nothing new, the country shows Source limit reached and stops re-entering the queue until the source changes.

Documentation

Document Contents
Deployment Docker Compose, reverse proxy, upgrades, backup and restore, troubleshooting
API Authentication, endpoints, parameters, batch generation, errors
API keys What each provider is for, how to obtain keys, admin setup
Development Local setup, project layout, tests, release checks
Data sources Sources, publication rules, synchronization flow (Chinese)
Country strategies Per-country fields, coordinates, deduplication, validation (Chinese)

License

Source code is released under the MIT License. Upstream datasets keep their own licenses and attribution requirements; see the data sources document.

Community

address (daimon3332/address)

Searching Database…

2K ·GitHub
Address
What is this?A self-hosted generator of addresses that really exist, taken from official registries and open map data, plus synthetic test profiles. It covers 27 countries and regions.
Is it a library or a web service?A web service: you deploy it yourself as a Docker Compose stack with a web UI, an admin console and a bearer-token JSON API.
How do I get it running?On a Linux host with Docker, run 'docker compose up -d' next to the Compose file. On first start it generates its own secrets, runs migrations and starts the API and sync service. Then sign in with the initial password 'admin', change it when prompted, and create an API token if external clients need one.
What do I need first?Linux on AMD64 or ARM64, Docker Engine 24+ with Compose v2, and 4 GB RAM (8 GB or more is recommended for the first import of large countries). No third-party keys are required.
Will every country have complete data?No. A country counts as complete only when its valid-address total, lowest-level admin coverage and per-level node minimums are all met. If a source has nothing new, the country stops at 'Source limit reached' until the source changes.
Can I get addresses from just one city or district?Yes: region, city, district and postcode filters follow each country's administrative hierarchy. A filter with no data returns an error instead of switching to another area.
How does the API work?It is a bearer-authenticated JSON API for single and batch generation, location search, coverage and address translation, documented with an OpenAPI 3.1 file.
Can I check results on a map?Yes: map previews are supported, and each result can be opened in Google Maps or AMap, copied, exported or saved to favorites.
Where do the addresses come from?China uses residential communities. Other countries use premise and street-level addresses from official registries and open map data, each labelled with its precision and residential evidence.
What are similar projects?algeria-geo, itsaplan, fleetbase, pictaria-server, directus, printfilm, rankme.fast, hivepaas
Which topics is it in?synthetic-data, open-data, geolocation, geospatial, openapi, admin-dashboard, self-hosting, i18n, multilingual, postgresql, china, docker-compose
Creator
daimon3332
Size
9.6 MB
Stars
2K
Updated
CommitNov 04Releasev2.4.1Nov 04
Age
3mo
Commits · 90 Days