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 стран и регионов.
Это библиотека или веб-сервис?Веб-сервис: его нужно развернуть самостоятельно как стек Docker Compose с веб-интерфейсом, консолью администратора и JSON API с авторизацией по bearer-токену.
Как его запустить?На хосте Linux с Docker выполните 'docker compose up -d' рядом с файлом Compose. При первом запуске он сам генерирует секреты, применяет миграции и запускает API и сервис синхронизации. Затем войдите с начальным паролем 'admin', смените его по запросу и создайте API-токен, если внешним клиентам он нужен.
Что нужно в первую очередь?Linux на AMD64 или ARM64, Docker Engine 24+ с Compose v2 и 4 ГБ оперативной памяти (для первого импорта больших стран рекомендуется 8 ГБ или больше). Сторонние ключи не требуются.
Будут ли данные полными для каждой страны?Нет. Страна считается полностью заполненной только тогда, когда выполнены все три условия: достигнут общий объём корректных адресов, покрытие на самом нижнем административном уровне и минимальное количество узлов на каждом уровне. Если в источнике нет ничего нового, страна останавливается со статусом 'Source limit reached', пока источник не изменится.
Можно ли получить адреса только из одного города или района?Да: фильтры по региону, городу, району и почтовому индексу следуют административной иерархии каждой страны. Если по фильтру нет данных, возвращается ошибка, а не подставляется другой район.
Как работает API?Это JSON API с авторизацией по bearer-токену для генерации одиночных адресов и пакетной генерации, поиска по местоположению, проверки покрытия и перевода адресов; описан в файле OpenAPI 3.1.
Можно ли проверить результаты на карте?Да: поддерживается предпросмотр на карте, а каждый результат можно открыть в Google Maps или AMap, скопировать, экспортировать или добавить в избранное.
Откуда берутся адреса?Для Китая используются жилые комплексы. Для остальных стран используются адреса уровня зданий и улиц из официальных реестров и открытых картографических данных; каждый помечен своей точностью и признаками жилого характера.
Какие есть похожие проекты?algeria-geo, itsaplan, fleetbase, directus, pictaria-server, printfilm, rankme.fast, hivepaas
Автор
daimon3332
Размер
13.2 MB
Звёзды
2.3K
Возраст
4 мес
Коммиты · 90 дней