UUID Generator Actor 🔑

A robust, high-performance Actor for generating universally unique identifiers (UUIDs) in bulk on the Apify platform.

🎯 Overview

The UUID Generator Actor provides a professional solution for generating RFC-compliant universally unique identifiers at scale. Whether you need a handful of UUIDs for testing or thousands for production data systems, this Actor delivers fast, reliable, and standards-compliant results.

Key Features

✨ Multiple UUID Versions

• UUID v1: Timestamp-based identifiers (includes MAC address and time)
• UUID v4: Random/pseudo-random identifiers (most common)
• UUID v5: Namespace-based identifiers (deterministic, based on namespace + name)

🚀 Bulk Generation

• Generate up to 100,000 UUIDs in a single run
• Optimized for performance and memory efficiency
• Progress tracking and detailed logging

📊 Flexible Output Formats

• JSON: Structured data with metadata
• CSV: Spreadsheet-compatible format
• Plain Text: One UUID per line

⚙️ Customizable Options

• Uppercase/lowercase formatting
• With or without hyphens
• Optional timestamps and indexing
• Namespace configuration for UUID v5

🎬 Quick Start

Basic Usage

1. Open the Actor in Apify Console
2. Configure your input parameters:

   {
     "uuidVersion": "v4",
     "quantity": 100,
     "outputFormat": "json"
   }
   

3. Click Start and retrieve your UUIDs from the dataset

UUID v4 (Random) - Default

Generate 1,000 random UUIDs:

{
  "uuidVersion": "v4",
  "quantity": 1000,
  "outputFormat": "json",
  "includeHyphens": true,
  "includeUppercase": false
}

Output:

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "version": "v4"
  },
  {
    "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "version": "v4"
  }
]

UUID v1 (Timestamp-based)

Generate time-ordered UUIDs with timestamps:

{
  "uuidVersion": "v1",
  "quantity": 50,
  "outputFormat": "json",
  "addTimestamp": true,
  "addIndex": true
}

Output:

[
  {
    "uuid": "6c84fb90-12c4-11e1-840d-7b25c5ee775a",
    "index": 1,
    "timestamp": "2025-12-28T10:30:45.123456Z",
    "version": "v1"
  }
]

UUID v5 (Namespace-based)

Generate deterministic UUIDs based on namespace and name:

{
  "uuidVersion": "v5",
  "quantity": 10,
  "namespace": "dns",
  "name": "example.com",
  "outputFormat": "json"
}

Output:

[
  {
    "uuid": "cfbff0d1-9375-5685-968c-48ce8b15ae17",
    "version": "v5"
  }
]

Plain Text Output

Generate UUIDs without hyphens in plain text format:

{
  "uuidVersion": "v4",
  "quantity": 5,
  "outputFormat": "txt",
  "includeHyphens": false,
  "includeUppercase": true
}

Output (stored in key-value store):

550E8400E29B41D4A716446655440000
6BA7B8109DAD11D180B400C04FD430C8
F47AC10B58CC4372A5670E02B2C3D479
9B76C58E9A0B4F1E8E9D3C8A6F4E2D1B
3F2504E0D7E911E19A1F0242AC120002

📋 Input Parameters

Parameter	Type	Required	Default	Description
uuidVersion	String	Yes	"v4"	UUID version: "v1", "v4", or "v5"
quantity	Integer	Yes	10	Number of UUIDs to generate (1-100,000)
outputFormat	String	Yes	"json"	Output format: "json", "csv", or "txt"
namespace	String	No	"dns"	Namespace for v5: "dns", "url", "oid", "x500", or custom UUID
name	String	Conditional	-	Name string for v5 (required for v5)
includeHyphens	Boolean	No	true	Include hyphens in UUID format
includeUppercase	Boolean	No	false	Convert UUIDs to uppercase
addTimestamp	Boolean	No	false	Include generation timestamp
addIndex	Boolean	No	false	Include sequential index number

Namespace Options for UUID v5

• dns - Domain Name System namespace
• url - URL namespace
• oid - ISO OID namespace
• x500 - X.500 DN namespace
• Custom UUID string (e.g., "6ba7b810-9dad-11d1-80b4-00c04fd430c8")

📤 Output

JSON Format (Dataset)

All runs save data to the Apify dataset. JSON format includes structured objects:

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "version": "v4",
    "index": 1,
    "timestamp": "2025-12-28T10:30:45.123456Z"
  }
]

CSV Format (Key-Value Store)

CSV output is saved to the key-value store with key OUTPUT:

uuid,version,index,timestamp
550e8400-e29b-41d4-a716-446655440000,v4,1,2025-12-28T10:30:45.123456Z
6ba7b810-9dad-11d1-80b4-00c04fd430c8,v4,2,2025-12-28T10:30:45.123456Z

Plain Text Format (Key-Value Store)

Plain text output (one UUID per line) is saved to the key-value store:

550e8400-e29b-41d4-a716-446655440000
6ba7b810-9dad-11d1-80b4-00c04fd430c8
f47ac10b-58cc-4372-a567-0e02b2c3d479

🎯 Use Cases

Software Development

• Generate unique identifiers for database records
• Create API keys and session tokens
• Test data generation for QA environments

Database Administration

• Populate primary key columns
• Generate unique constraint values
• Database migration and testing

API Development

• Create unique request IDs for distributed systems
• Generate idempotency keys
• Microservices correlation IDs

Testing & QA

• Load testing with unique identifiers
• Automated test data generation
• Performance testing scenarios

System Integration

• ETL processes requiring unique identifiers
• Data synchronization across systems
• Event tracking and logging

🏗️ Architecture

This Actor is built with:

• Python 3.13 - Latest Python runtime
• Apify SDK - For seamless platform integration
• UUID Module - Python's built-in RFC 4122 compliant UUID library

Performance Characteristics

• Speed: Generates 10,000 UUIDs in ~1-2 seconds
• Memory: Efficient batch processing for large quantities
• Scalability: Handles up to 100,000 UUIDs per run
• Reliability: Built-in error handling and validation

🔧 Technical Details

UUID Versions Explained

UUID v1 (Timestamp-based)

• Format: time_low-time_mid-time_high_and_version-clock_seq-node
• Includes: 60-bit timestamp + 48-bit MAC address
• Use case: When temporal ordering is important
• Note: May expose MAC address (privacy consideration)

UUID v4 (Random)

• Format: 122 random bits + 6 fixed bits
• Cryptographically strong pseudo-random
• Use case: General purpose, most common
• Collision probability: Extremely low (~1 in 10^36)

UUID v5 (Namespace + Name)

• Based on SHA-1 hash of namespace + name
• Deterministic: Same input = same UUID
• Use case: When reproducibility is needed
• Supports standard and custom namespaces

RFC Compliance

All generated UUIDs comply with RFC 4122 specifications:

• Proper version bits (bits 12-15)
• Proper variant bits (bits 62-63)
• Standard hyphenated format (8-4-4-4-12)

🚀 Running Locally

Prerequisites

• Python 3.9+
• Apify CLI (npm install -g apify-cli)

Installation

# Clone or download the Actor
git clone <your-repo-url>
cd uuid-generator

# Install dependencies
pip install -r requirements.txt

# Run locally
apify run

Development

# Login to Apify
apify login

# Test locally
apify run --purge

# Push to Apify platform
apify push

📊 Examples & Tutorials

Example 1: Database Seeding

Generate 5,000 UUIDs for database primary keys:

{
  "uuidVersion": "v4",
  "quantity": 5000,
  "outputFormat": "csv",
  "includeHyphens": true,
  "addIndex": true
}

Import the CSV directly into your database:

LOAD DATA INFILE 'uuids.csv'
INTO TABLE your_table
FIELDS TERMINATED BY ','
(uuid_column, @dummy, id_column);

Example 2: API Testing

Generate test identifiers with timestamps:

{
  "uuidVersion": "v1",
  "quantity": 1000,
  "outputFormat": "json",
  "addTimestamp": true,
  "addIndex": true
}

Example 3: Namespace-based IDs

Generate consistent UUIDs for domain names:

{
  "uuidVersion": "v5",
  "quantity": 100,
  "namespace": "dns",
  "name": "api.example.com",
  "outputFormat": "json"
}

🔗 Integration

Using Apify API

const ApifyClient = require('apify-client');

const client = new ApifyClient({
    token: 'YOUR_API_TOKEN',
});

const input = {
    uuidVersion: 'v4',
    quantity: 1000,
    outputFormat: 'json',
};

const run = await client.actor('YOUR_USERNAME/uuid-generator').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(`Generated ${items.length} UUIDs`);

Python Integration

from apify_client import ApifyClient

client = ApifyClient('YOUR_API_TOKEN')

run = client.actor('YOUR_USERNAME/uuid-generator').call(
    run_input={
        'uuidVersion': 'v4',
        'quantity': 1000,
        'outputFormat': 'json',
    }
)

dataset = client.dataset(run['defaultDatasetId'])
items = dataset.list_items().items

print(f"Generated {len(items)} UUIDs")

🤝 Support & Contribution

Issues & Feedback

Found a bug or have a feature request? Please open an issue on the GitHub repository.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This Actor is available for use on the Apify platform. See Apify Terms of Service for details.

🏆 Apify 1 Million Challenge

This Actor was developed as part of the Apify 1 Million Challenge, demonstrating the power and flexibility of the Apify platform for building scalable automation tools.

📚 Resources

• Apify Documentation
• Apify SDK for Python
• UUID RFC 4122 Specification
• Python UUID Module

---

Built with ❤️ for the Apify community