address README

项目的 README,来自 github.com/daimon3332/address。合并为一个 markdown 文件: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)

正在搜索数据库…

2.3K ·GitHub
这是什么?一个可自行部署的地址生成器,生成的地址真实存在,来源于官方登记机构和开放地图数据,同时也可生成合成的测试档案。覆盖 27 个国家和地区。
这是程序库还是 Web 服务?是 Web 服务:你需要自己用 Docker Compose 部署,它带有 Web 界面、管理控制台,以及基于 Bearer Token 的 JSON API。
怎么把它跑起来?在装有 Docker 的 Linux 主机上,于 Compose 文件旁运行 'docker compose up -d'。首次启动时,它会自动生成自己的密钥,执行数据库迁移,并启动 API 和同步服务。然后使用初始密码 'admin' 登录,并按提示修改密码;如果外部客户端需要访问,再创建一个 API Token。
我首先需要准备什么?AMD64 或 ARM64 架构的 Linux、带 Compose v2 的 Docker Engine 24+,以及 4 GB 内存(首次导入大国家数据时建议 8 GB 或更多)。无需任何第三方密钥。
每个国家的数据都完整吗?不一定。只有当某国家的有效地址总数、最低层级行政区覆盖率以及各层级节点的最低数量全部达标,才算完整。如果数据源没有新内容,该国家会停在“已达到数据源上限”,直到数据源发生变化。
能只获取某个城市或区的地址吗?可以:地区、城市、区和邮编筛选会遵循各国的行政层级结构。如果筛选条件下没有数据,会返回错误,而不会自动切换到其他区域。
API 是怎么工作的?它是一个使用 Bearer 认证的 JSON API,支持单条和批量生成、地点搜索、覆盖情况查询以及地址翻译,并提供 OpenAPI 3.1 文件作为文档。
能在地图上查看结果吗?可以:支持地图预览,每条结果都可以在 Google 地图或高德地图中打开,也可以复制、导出或收藏。
这些地址从哪里来?中国使用住宅小区数据。其他国家使用来自官方登记机构和开放地图数据的门牌号及街道级地址,每条地址都标注了精度等级和住宅证据。
大小
13.2 MB
星标
2.3K
时长
4个月
提交 · 90 天