Real Random US Tax-Free State Address Generator

This repository contains the open-source frontend core engine of MockAddress, for generating authentic-format test addresses and MAC address data across multiple countries/regions.
Full production site: https://mockaddress.com/

🇨🇳 中文用户请查看：README_CN.md（中文文档）

Project Overview

MockAddress Core is a pure frontend, zero backend dependency test data engine designed for developers and QA engineers, providing:

• Authentic-format address data conforming to official postal standards (verifiable on Google Maps / Apple Maps)
• Optional identity fields + credit card fields (for form/payment flow testing only)
• MAC address generation + vendor lookup + IPv6 Link-Local derivation and other network test data

All core logic runs entirely in the browser and can be deployed to any static hosting environment (GitHub Pages, Cloudflare Pages, Vercel, etc.).

Note

: This repository only open-sources the engine and base styles.
Large-scale address datasets and production site page templates remain MockAddress private assets for online services.

---

Key Features

• Multi-Country/Region Address Generation (Engine Support)

  • Supports generating address structures conforming to local postal standards for multiple countries/regions
  • Address fields include complete information: street, city, state/province, postal code, country, etc.
  • Can be extended with localized fields based on country (e.g., Japanese address hierarchy, Hong Kong bilingual addresses)

• Authentic Format & Verifiable

  • Address data is based on official postal/statistical data + OpenStreetMap and other public data sources, cleaned and organized
  • Generated results are designed to be verifiable on Google Maps / Apple Maps and other mapping services
  • Suitable for registration forms, payment pages, tax calculation logic, and other scenarios requiring strict address format validation

• Optional Identity & Credit Card Fields (Testing Only)

  • Optionally generate name, gender, date of birth, occupation, localized ID number formats, etc.
  • Optionally generate credit card numbers (Luhn-validated), expiration date, CVC, and other fields
  • All identity/card data is randomly generated and does not correspond to any real individuals or real cards

• Batch Export & Automation-Friendly

  • Built-in CSV / JSON export capabilities
  • Suitable for automated testing, regression testing, CI/CD pipelines for bulk test data injection

• MAC Tools

  • Generate MAC addresses in multiple formats (colon, hyphen, dot, no separator, etc.)
  • Vendor identification based on OUI dataset
  • Support for deriving IPv6 Link-Local addresses from MAC addresses
  • All logic runs locally in the browser, suitable for network testing, device simulation, and script development

• Pure Frontend, Privacy-First

  • No backend service dependency, all logic completed in frontend JS
  • Optionally save generated results to browser localStorage, servers do not store any generated data

---

Repository Structure

mockaddress-core/
├── src/
│   ├── js/
│   │   ├── address-generator.js     # Address/identity/credit card generation engine
│   │   ├── mac-generator.js         # MAC generation and vendor lookup
│   │   ├── storage.js               # Storage, rate limiting, export utilities
│   │   ├── language-switcher.js     # Multi-language routing and internal link rewriting
│   │   ├── utils.js                 # General utility functions
│   │   └── config.js                # Configuration module
│   └── css/
│       └── main.css                 # Universal dark theme and base UI component styles
├── README.md                         # Project documentation (this file)
├── README_EN.md                      # English documentation
├── LICENSE                           # Open source license (MIT)
├── CONTRIBUTING.md                   # Contribution guidelines
├── ROADMAP.md                        # Roadmap
└── .gitignore                        # Git ignore rules

Reminder: This repository does not include production site HTML files or large-scale data files data/*.json.
These are used for online deployment and are not part of this open-source release.

---

Usage

Quick Start

Option 1: Direct Use (if your data directory is data/)

<script type="module">
  import { generateUSAddress } from './src/js/address-generator.js'
  
  // Direct use, will automatically detect data/ directory
  const address = await generateUSAddress('CA')
  console.log(address)
</script>

Option 2: Custom Data Path (Recommended)

<script type="module">
  // 1. Import configuration module
  import { configure } from './src/js/config.js'
  import { generateUSAddress } from './src/js/address-generator.js'
  
  // 2. Configure your data path
  configure({
    dataBasePath: 'my-data/',  // Your data directory
    autoDetectPaths: false     // Disable auto-detection
  })
  
  // 3. Use normally
  const address = await generateUSAddress('CA')
  console.log(address)
</script>

Configuration Options

• dataBasePath: Base path for your data files (e.g., 'my-data/', '/static/data/')
• autoDetectPaths: Whether to enable automatic path detection (default true, suitable for mockaddress.com's multi-language structure)

Important

: If you don't call configure(), the code will use default behavior, completely unaffected by mockaddress.com's normal operation.

Available Functions

• generateUSAddress(state) - US addresses
• generateHKAddress(region, isEnglish) - Hong Kong addresses
• generateUKAddress(region) - UK addresses
• generateCAAddress(province) - Canada addresses
• generateJPAddress(prefecture) - Japan addresses
• generateINAddress(state) - India addresses
• generateTWAddress(county) - Taiwan addresses
• generateSGAddress(state) - Singapore addresses
• generateDEAddress(state) - Germany addresses
• generateTaxFreeAddress(state) - US tax-free state addresses
• generateIdentityInfo(address) - Identity information
• generateCreditCardInfo() - Credit card information (testing only)

Code Examples

Generate US Tax-Free State Address:

import { generateTaxFreeAddress } from './src/js/address-generator.js';

// Generate address for Oregon (tax-free state)
const address = await generateTaxFreeAddress('OR');
console.log(address);
// Output: { street: "123 Main St", city: "Portland", state: "OR", zip: "97201", ... }

Generate Address with Identity Info:

import { generateUSAddress, generateIdentityInfo } from './src/js/address-generator.js';

const address = await generateUSAddress('CA');
const identity = generateIdentityInfo(address);
console.log({ ...address, ...identity });
// Output includes: name, gender, dateOfBirth, occupation, ssn, etc.

Generate MAC Address:

import { generateMACAddress, lookupVendor } from './src/js/mac-generator.js';

const mac = generateMACAddress('colon'); // 'aa:bb:cc:dd:ee:ff'
const vendor = await lookupVendor(mac);
console.log(vendor); // Vendor information from OUI database

Export to CSV/JSON:

import { exportToCSV, exportToJSON, getAllSavedAddresses } from './src/js/storage.js';

// After saving some addresses
const addresses = getAllSavedAddresses();
const csv = exportToCSV(addresses);
const json = exportToJSON(addresses);

// Download or use the exported data
console.log(csv);
console.log(json);

Offline Local-Only Usage (Run Everything on Your Own Machine)

If, like me, you prefer to keep all data and logic on your own computer only, without relying on any external server, you can treat MockAddress Core as a pure static site and run it via a simple local HTTP server:

• My development environment is a Windows PC with:
  • A modern browser (Chrome / Edge, etc.)
  • Python / PHP / Node.js (at least one of them; in my case I have all three installed)
• Clone this repository to a local directory, e.g. D:\mockaddress-core\.
• In the project root, create a start-local-server.bat with the following content to start a local server and automatically open http://localhost:8000:

@echo off

echo Starting local server...

echo.

REM Check if Python 3 is available

python --version >nul 2>&1

if %errorlevel% equ 0 (

    python -c "import sys; sys.exit(0 if sys.version_info >= (3, 0) else 1)" >nul 2>&1

    if %errorlevel% equ 0 (

        echo Found Python 3

        echo Starting server on http://localhost:8000

        echo Press Ctrl+C to stop

        echo.

        timeout /t 2 /nobreak >nul

        start http://localhost:8000

        python -m http.server 8000

        exit /b 0

    )

)

REM Check if Python 2 is available

python --version >nul 2>&1

if %errorlevel% equ 0 (

    python -c "import sys; sys.exit(0 if sys.version_info < (3, 0) else 1)" >nul 2>&1

    if %errorlevel% equ 0 (

        echo Found Python 2

        echo Starting server on http://localhost:8000

        echo Press Ctrl+C to stop

        echo.

        timeout /t 2 /nobreak >nul

        start http://localhost:8000

        python -m SimpleHTTPServer 8000

        exit /b 0

    )

)

REM Check if PHP is available

php --version >nul 2>&1

if %errorlevel% equ 0 (

    echo Found PHP

    echo Starting server on http://localhost:8000

    echo Press Ctrl+C to stop

    echo.

    timeout /t 2 /nobreak >nul

    start http://localhost:8000

    php -S localhost:8000

    exit /b 0

)

REM Check if Node.js is available

where npx >nul 2>&1

if %errorlevel% equ 0 (

    echo Found Node.js

    echo Starting server on http://localhost:8000

    echo Press Ctrl+C to stop

    echo.

    timeout /t 2 /nobreak >nul

    start http://localhost:8000

    npx --yes http-server -p 8000

    exit /b 0

)

echo Error: No server found

echo Please install Python, PHP, or Node.js

pause

exit /b 1

How to use:

• Double-click start-local-server.bat. The script will try Python 3 → Python 2 → PHP → Node.js in order, start the first available local server, and open http://localhost:8000 in your browser.
• From that point on, all address generation logic— including the US address generator and the Hong Kong English/Chinese address generator—runs entirely on your own machine, with no Internet connection required.
• This setup is ideal for intranet environments or teams with strict privacy/compliance requirements.

For detailed usage instructions, see 使用说明.md (Usage Guide in Chinese).

You can also refer to our production site https://mockaddress.com/ to see real-world usage scenarios and UI design, then customize as needed in your own project.

---

Deployment Examples: Cloudflare & VPS (Static Hosting)

The following steps are for developers who want to deploy mockaddress-core themselves, describing only the simplest path for README purposes.

Deploy with Cloudflare Pages (Recommended for Frontend / Zero Ops Cost Scenarios)

1. Create a repository on GitHub (e.g., mockaddress-core), push this project's code to it.
2. Log in to Cloudflare, go to Pages, select "Create a project with Git provider", and bind this repository.
3. Build settings:
   • Framework preset: None / Static Site
   • Build command: Leave empty (or npm run build if you add a build process later)
   • Output directory: Set to project root (or your build output directory)
4. After deployment, ensure:
   • All JS/CSS load correctly via <script type="module"> / <link> relative paths;
   • If you have multi-language subdirectory structures (e.g., /en/, /ru/), maintain the same directory hierarchy in the repository.

Note

: If you only want to open-source the core and don't want to expose the full site, you can deploy only a minimal demo page (or just screenshots, directing users to the production site in the README).

Deploy with VPS + Nginx (Suitable for Existing Servers)

1. Build or organize the static file structure locally (src/js, src/css, and your HTML entry).
2. Upload these static files to your VPS (e.g., /var/www/mockaddress-core directory).
3. Configure Nginx site (example):

server {
    listen 80;
    server_name your-domain.com;

    root /var/www/mockaddress-core;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

4. Reload Nginx: nginx -s reload or use the corresponding service management command.
5. Open your browser and visit http://your-domain.com to confirm address generation/MAC tools and other features work correctly.

VPS deployment essence: Host this set of frontend files as a pure static site, no Node.js / PHP / database or other backend environment required.

---

Data Sources & Authenticity (Brief Overview)

For complete data sources and more detailed authority information, refer to our publicly available llms documentation online. Here is a brief summary:

• Primarily based on official postal/statistical data and geographic data published by various countries
• Supplemented with open-source geographic data projects such as OpenStreetMap / GeoNames / OpenAddresses
• Cleaned and randomly combined through custom rules to ensure:
  • Address structure conforms to local postal standards
  • Address content is designed to be verifiable on mainstream mapping services
  • Not directly associated with any real personal identity

---

Open Source Scope & Non-Open Source Parts

This repository open-sources the following:

• Frontend engine logic for address/identity/credit card field generation
• Frontend logic for MAC generation and vendor lookup
• Base UI styles (CSS) supporting the above engines
• General routing tools for multi-language static sites (e.g., language-switcher.js)

The following are not included:

• Production site HTML page templates and all copy
• Large-scale address data files (data/*.json production datasets)
• Internal operations scripts, deployment configurations, etc.

---

Suitable & Unsuitable Use Cases (Important)

Suitable Use Cases (Examples):

• Software development and testing environments
• Form validation logic testing
• Cross-border e-commerce / cross-border business address form filling simulation
• UI/UX prototyping and demos
• Educational demonstrations and technical sharing
• Network testing and device simulation (MAC tools)

Unsuitable Use Cases:

• Real mailing and shipping addresses
• Long-term real-name account registration and operation
• Circumventing KYC / risk control / legal regulatory purposes
• Any illegal or gray-area uses

---

Roadmap (Example)

Planned improvements for the open-source core (actual roadmap subject to ROADMAP.md):

• Provide clearer TypeScript type definitions
• Split country-specific address generation logic for easier standalone extension/on-demand import
• Enrich export formats and integration examples for easier CI/CD pipeline integration
• Add support for more countries/regions' address formats based on community feedback

---

Online Examples & Contact

• Production Site (Full Product, Multi-Language):
  • Chinese: https://mockaddress.com/
  • English: https://mockaddress.com/en/
  • Russian: https://mockaddress.com/ru/
  • Spanish: https://mockaddress.com/es/
  • Portuguese: https://mockaddress.com/pt/
• For more background and information about this site, see the About/Help/Blog pages on the site.

If you have any questions or suggestions during use, welcome to participate via Issues or PRs to help improve this frontend test data engine.

---

GitHub Topics

Recommended topics for this repository (copy and paste into GitHub repository settings):

Core Functionality Tags

address-generator, random-address, fake-address, tax-free-state, real-address, 
random-us-address, random-address-generator-for-testing, us-dummy-address-generator

Regional Address Tags

hong-kong-address-random, random-address-in-hong-kong, hong-kong-random-address,
japan-address-generator-tokyo, random-japan-address, taiwan-address-format, 
taiwan-address-sample, canada-address, uk-address, india-address, singapore-address

Technical Stack Tags

javascript, frontend, browser-only, no-backend, static-site, 
privacy-first, openstreetmap, address-validation, postal-standards

Use Case Tags

test-data, devtools, qa, testing, mock-data, form-testing, 
automation, ci-cd, csv-export, json-export, mac-address

Quick Copy (All Topics):

address-generator, random-address, fake-address, tax-free-state, real-address, random-us-address, random-address-generator-for-testing, us-dummy-address-generator, hong-kong-address-random, random-address-in-hong-kong, hong-kong-random-address, japan-address-generator-tokyo, random-japan-address, taiwan-address-format, taiwan-address-sample, javascript, frontend, test-data, devtools, qa, testing, mock-data, browser-only, privacy-first, csv-export, json-export, mac-address

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

💰 Support & Technical Services

Cryptocurrency Donations

You can also support us via cryptocurrency:

Ethereum / USDT (ERC-20):

0x6Df562A8B669bf90EAe5ccB0E0440eb9DF237E4e

USDT (TRC-20):

TYz2SP7GtL84t14CeL7tnhHLgeako3haHW

Note

: Cryptocurrency donations are non-refundable. Please double-check the address before sending.

📊 Technical Services Support

Need technical support for your project? Feel free to contact us for paid services and technical assistance.

📧 Email: jietoushiren01@gmail.com