go-faker/README.md

Go-Faker

High-performance Ethiopian fake data generator for load testing and development.

Features

• Seeded randomness - Reproducible datasets across runs
• Batch generation - Generate thousands of records in a single call
• Rich Ethiopian data - Names, cities, regions, phone numbers (+251), and more
• Two modes - Use as a Go library or HTTP API server
• Fast - ~150k records/second throughput

Quick Start

CLI

# Generate 10 person records
./gofaker -count 10 -type person

# Generate 100 product records with specific fields
./gofaker -count 100 -type product -fields name,price,sku

# Use a seed for reproducible data
./gofaker -count 50 -type person -seed my-test-seed

API Server

# Start server
./gofaker -server -addr :8080

# Generate via HTTP
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"seed":"test","count":10,"type":"person","fields":["first_name","phone","email"]}'

Library

import "go-faker"

f := faker.New("my-seed")

// Generate single record
person := f.GeneratePerson([]string{"first_name", "phone", "email"})

// Generate batch
persons := f.GenerateBatch(1000, "person", []string{"first_name", "email", "city"})

Data Types

person

Field	Description
first_name	Ethiopian first name
last_name	Ethiopian last name
full_name	First + last name
phone	Ethiopian mobile (+2519x...)
email	Generated email address
gender	Male/Female
age	18-90
language	Ethiopian language
city	Ethiopian city
region	Ethiopian region
nationality	Ethiopian/nearby
occupation	Job title
company	Ethiopian company
blood_type	Blood type
date_of_birth	YYYY-MM-DD
username	Generated username
password	Secure random password

address

Field	Description
street	Street name
city	City
region	Region
sub_city	Sub-city (Addis Ababa)
postal_code	4-digit code
zone	Zone number
woreda	Woreda
kebele	Kebele number
house_number	House identifier
latitude	GPS coordinate
longitude	GPS coordinate

product

Field	Description
name	Product name
category	Product category
price	Price in ETB
sku	Stock keeping unit
brand	Brand name
description	Product description
weight	Weight in kg
stock	Stock quantity
expiry_date	Future date
manufactured_date	Past date

analytics

Field	Description
user_id	user-XXXXX
event	Event type
timestamp	RFC3339 timestamp
amount	Transaction amount
currency	ETB
session_id	Session identifier
page_url	Page URL
ip_address	IP address (10.x.x.x)
device_type	Device type
browser	Browser name
os	Operating system
country	Country
referrer	Referrer URL

API Reference

POST /generate

Generate fake data.

Request:

{
  "seed": "optional-seed-string",
  "count": 100,
  "type": "person",
  "fields": ["first_name", "email", "phone"]
}

Response:

{
  "data": [
    {"first_name": "Tadesse", "email": "Tadesse@email.com", "phone": "+251911234567"}
  ],
  "meta": {
    "count": 100,
    "seed": "optional-seed-string",
    "generated_at": "2026-05-02T10:00:00Z"
  },
  "format": "json"
}

GET /fields

List all valid fields per data type.

GET /health

Health check endpoint.

Performance

Records	Time	Rate
10,000	0.4s	~25k/s
100,000	0.7s	~143k/s

License

MIT