# Real Random US Tax-Free State Address Generator
[](LICENSE)
[]()
[]()
[]()
[]()
[]()
[]()
> 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:
>
> π¨π³ **δΈζη¨ζ·θ―·ζ₯ηοΌ[README_CN.md](./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/`)**
```html
```
**Option 2: Custom Data Path (Recommended)**
```html
```
### 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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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`:
```bat
@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`](./δ½Ώη¨θ―΄ζ.md) (Usage Guide in Chinese).
You can also refer to our production site 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 `