# Address
**Self-hosted real-address generator backed by official registries and open map data for 27 countries and regions**
English · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md)
[](https://github.com/daimon3332/address/actions/workflows/ci.yml)
[](https://hub.docker.com/r/daimon23/address)
[](https://nodejs.org/)
[](https://www.postgresql.org/)
[](LICENSE)
[](https://address.333186.xyz)
## 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
```bash
# 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:
```dotenv
ALLOWED_ORIGINS=https://address.example.com
TRUST_PROXY=true
COOKIE_SECURE=true
```
See the [deployment guide](docs/DEPLOYMENT.md) 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
```bash
curl -fsS "http://127.0.0.1:8787/api/v1/generate?country=US&city=Seattle" \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
```json
{
"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](docs/API.md) 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](docs/API_KEYS.md) for how to obtain each one.
## Screenshots
