Repolode
Submit
daimon3332

daimon3332/address

Self-hosted address generator that returns real addresses from official registries and open map data for 27 countries and regions.

View on GitHubWebsite
Stars
2,132
Forks
336
Open issues
1
Last commit
3 days ago

What is it?

Address generates addresses for testing and demos that correspond to real places rather than randomly assembled strings. Each record is drawn from an official address register, open map data, or a validated geocoding result, and includes its source, precision, and coordinates. Fields without data are left empty instead of being filled in.

The project is deployed with a single Docker Compose file that runs the web app, PostgreSQL, migrations, and a background sync service. It offers region, city, district, and postcode filters that follow each country's administrative hierarchy, output in ten display languages, and an admin console for managing sources, API tokens, and access control. A Bearer-authenticated JSON API supports single and batch generation, location search, coverage queries, and address translation, with an OpenAPI 3.1 document.

Addresses can be copied, exported, saved, or opened in Google Maps or AMap. Optional third-party keys extend data for specific countries or enable online translation.

Key features

  • 01Covers 27 countries and regions with filters that follow each country's administrative hierarchy.
  • 02Each address includes its source, match precision, and coordinates.
  • 03Output is available in ten display languages, including several Chinese, Japanese, Korean, and European languages.
  • 04Incremental background sync with retry limits and source-exhaustion detection.
  • 05Bearer-authenticated API for single and batch generation, location search, and translation.
  • 06Single Docker Compose deployment that generates its own secrets on first start.

Use cases

  • Filling test data for checkout and registration forms.
  • Validating address formats across multiple countries.
  • Creating realistic addresses for logistics or mapping demos.
  • Generating batches of addresses through the API for test pipelines.

Quick start

  1. 1

    Download the Docker Compose file

    curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/daimon3332/address/main/docker-compose.yml
  2. 2

    Start all services

    docker compose up -d
  3. 3

    Check readiness

    curl -fsS http://127.0.0.1:8787/api/v1/ready

Things to know

  • Requires Linux (AMD64 or ARM64) with Docker Engine 24+ and Compose v2.
  • Needs at least 4 GB RAM, and 8 GB or more is recommended for the first import of large countries.
  • Upstream datasets keep their own licenses and attribution requirements.

In collections

Self-hosted apps

Topics

#address-generation#mock-data#test-data#self-hosted#geocoding#openstreetmap#docker#api#address#address-generator

FAQ

What is address?
Self-hosted address generator that returns real addresses from official registries and open map data for 27 countries and regions. Address generates addresses for testing and demos that correspond to real places rather than randomly assembled strings. Each record is drawn from an official address register, open map data, or a validated geocoding result, and includes its source, precision, and coordinates. Fields without data are left empty instead of being filled in.
Is address free to use? What license does it have?
address is open source under the MIT license. Check the license terms before using it in commercial products.
Is address still maintained?
Actively maintained. The last commit to address was on Nov 4, 2026.
What can I use address for?
Filling test data for checkout and registration forms. Validating address formats across multiple countries. Creating realistic addresses for logistics or mapping demos. Generating batches of addresses through the API for test pipelines.
How do I install address?
Download the Docker Compose file: curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/daimon3332/address/main/docker-compose.yml Start all services: docker compose up -d Check readiness: curl -fsS http://127.0.0.1:8787/api/v1/ready
Where can I get address?
The source code and installation instructions are on GitHub: https://github.com/daimon3332/address

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects