DEV Community: Ankit Arora

Building a ~10M-Parameter GPT-Style Language Model on Simple Home Computer

Ankit Arora — Sat, 01 Aug 2026 21:09:39 +0000

A Complete Guide with Code Examples

Generative AI has transformed the way we build intelligent applications. Large Language Models (LLMs) such as GPT, Llama, and Gemma can write code, answer questions, summarize documents, and even reason through complex problems. While using these existing models is straightforward, understanding how they actually work is a different challenge.

Many engineers begin by fine-tuning existing models or using frameworks like Hugging Face. While these tools are incredibly valuable, they often hide the mechanics that make language models possible. Building a small GPT-style model from scratch is one of the best ways to understand the underlying concepts.

This article walks through the complete process of building a miniature Generative AI model using only PyTorch. By the end, you'll understand every major component of a Transformer-based language model and have a solid foundation for exploring larger architectures.

Although the model we'll build contains around 10 million parameters—tiny compared to today's billion-parameter models—it contains the same fundamental building blocks used in modern LLMs.

What You'll Build

Our goal is to create a character-level GPT model capable of learning patterns from text and generating new text one token at a time.

The journey consists of five major stages:

Build a tokenizer
Create a dataset for next-token prediction
Implement the Transformer architecture
Train the model
Generate text

Each stage builds on the previous one, gradually transforming raw text into an intelligent language model.

Setting Up Your Environment

First, prepare your Mac for machine learning:

# Install Xcode Command Line Tools
xcode-select --install

# Create project directory
mkdir my-gpt-from-scratch && cd my-gpt-from-scratch

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install torch numpy tqdm

Verify PyTorch can use your Mac's GPU:

import torch
print(f"MPS available: {torch.backends.mps.is_available()}")
print(f"MPS built: {torch.backends.mps.is_built()}")
# Should output: True, True

Project Structure

my-gpt-from-scratch/
│
├── tokenizer.py      # Character-level tokenizer
├── data.py           # Dataset and batching
├── model.py          # GPT architecture
├── train.py          # Training loop
├── generate.py       # Text generation
├── config.py         # Hyperparameters
├── utils.py          # Helper functions
└── data/
    └── input.txt     # Training corpus

Stage 1: Teaching the Computer to Read

Before a neural network can understand language, it must convert text into numbers. This process is called tokenization. For simplicity, we'll use a character-level tokenizer, where every unique character receives a unique integer.

# tokenizer.py

class CharTokenizer:
    def __init__(self, text):
        chars = sorted(list(set(text)))

        self.stoi = {ch:i for i,ch in enumerate(chars)}
        self.itos = {i:ch for ch,i in self.stoi.items()}

        self.vocab_size = len(chars)

    def encode(self, text):
        """Convert text to token IDs"""
        return [self.stoi[c] for c in text]

    def decode(self, ids):
        """Convert token IDs back to text"""
        return ''.join(self.itos[i] for i in ids)

Example Usage:

text = "hello world"
tok = CharTokenizer(text)

ids = tok.encode("hello")
print(ids)  # [1, 0, 2, 2, 3]

print(tok.decode(ids))  # hello

Stage 2: Creating Training Examples

Language models learn a surprisingly simple task: predict the next token.

Consider the sentence: "Machine learning is amazing"

During training, the model repeatedly sees examples like:

Input	Target
Machine	learning
Machine learning	is
Machine learning is	amazing

Instead of feeding the entire dataset every iteration, we'll create small chunks called contexts (or sequences).

# data.py

import torch

class TextDataset:
    def __init__(self, data, block_size):
        """
        data: list of token IDs
        block_size: context length (e.g., 256)
        """
        self.data = torch.tensor(data, dtype=torch.long)
        self.block_size = block_size

    def get_batch(self, batch_size):
        """Get a batch of input-target pairs"""
        # Random starting positions
        ix = torch.randint(
            len(self.data) - self.block_size - 1,
            (batch_size,)
        )

        # Input sequences
        x = torch.stack([
            self.data[i:i+self.block_size]
            for i in ix
        ])

        # Target sequences (shifted by 1)
        y = torch.stack([
            self.data[i+1:i+self.block_size+1]
            for i in ix
        ])

        return x, y

Stage 3: Building the Transformer

Modern language models are built using the Transformer architecture, introduced in the landmark paper "Attention Is All You Need."

Step 3.1: Token Embedding

Neural networks cannot operate directly on integer IDs. Instead, every token is mapped to a dense vector called an embedding.

import torch.nn as nn

# In your model class:
token_embedding = nn.Embedding(
    vocab_size,     # Number of unique tokens
    embedding_dim   # Size of each embedding vector (e.g., 384)
)

Step 3.2: Positional Embedding

Unlike humans, Transformers have no built-in understanding of sequence order. Without positional information, "dog bites man" and "man bites dog" appear identical.

# Positional embedding
position_embedding = nn.Embedding(
    block_size,     # Maximum sequence length
    embedding_dim   # Same as token embedding
)

# In forward pass:
B, T = x.shape  # Batch size, Sequence length

tok_emb = token_embedding(x)  # Shape: (B, T, n_embed)

pos = position_embedding(
    torch.arange(T, device=x.device)
)  # Shape: (T, n_embed)

x = tok_emb + pos  # Add position information

Step 3.3: Single-Head Self-Attention

Self-attention allows the model to weigh the importance of different tokens. Each token asks: "Which previous tokens should I pay attention to?"

class Head(nn.Module):
    def __init__(self, n_embed, head_size, block_size):
        super().__init__()

        self.key = nn.Linear(n_embed, head_size, bias=False)
        self.query = nn.Linear(n_embed, head_size, bias=False)
        self.value = nn.Linear(n_embed, head_size, bias=False)

        # Causal mask (prevents looking at future tokens)
        self.register_buffer(
            "tril",
            torch.tril(torch.ones(block_size, block_size))
        )

    def forward(self, x):
        B, T, C = x.shape

        # Compute key, query, value
        k = self.key(x)    # (B, T, head_size)
        q = self.query(x)  # (B, T, head_size)

        # Compute attention scores
        wei = q @ k.transpose(-2, -1)  # (B, T, T)

        # Scale (stabilizes gradients)
        wei = wei / (k.shape[-1] ** 0.5)

        # Apply causal mask
        wei = wei.masked_fill(
            self.tril[:T, :T] == 0,
            float("-inf")
        )

        # Convert to probabilities
        wei = wei.softmax(dim=-1)  # (B, T, T)

        # Apply attention to values
        v = self.value(x)  # (B, T, head_size)
        out = wei @ v      # (B, T, head_size)

        return out

Step 3.4: Multi-Head Attention

Because language contains many types of relationships, we use multiple attention heads. Different heads can specialize in different patterns.

class MultiHeadAttention(nn.Module):
    def __init__(self, num_heads, n_embed, block_size):
        super().__init__()

        head_size = n_embed // num_heads

        self.heads = nn.ModuleList([
            Head(n_embed, head_size, block_size)
            for _ in range(num_heads)
        ])

        self.proj = nn.Linear(n_embed, n_embed)

    def forward(self, x):
        # Run all heads and concatenate
        out = torch.cat(
            [h(x) for h in self.heads],
            dim=-1
        )

        return self.proj(out)

Step 3.5: Feed-Forward Network

After attention gathers information, each token passes through a small neural network that transforms the representation.

class FeedForward(nn.Module):
    def __init__(self, n_embed):
        super().__init__()

        self.net = nn.Sequential(
            nn.Linear(n_embed, 4 * n_embed),  # Expand
            nn.GELU(),                         # Activation
            nn.Linear(4 * n_embed, n_embed)    # Contract
        )

    def forward(self, x):
        return self.net(x)

Step 3.6: Transformer Block

Layer normalization and residual connections make training stable.

class Block(nn.Module):
    def __init__(self, n_embed, n_head, block_size):
        super().__init__()

        self.sa = MultiHeadAttention(n_head, n_embed, block_size)
        self.ffwd = FeedForward(n_embed)

        self.ln1 = nn.LayerNorm(n_embed)
        self.ln2 = nn.LayerNorm(n_embed)

    def forward(self, x):
        # Attention with residual connection
        x = x + self.sa(self.ln1(x))

        # Feed-forward with residual connection
        x = x + self.ffwd(self.ln2(x))

        return x

Step 3.7: Complete GPT Model

class GPT(nn.Module):
    def __init__(self, vocab_size, n_embed, n_head, n_layer, block_size):
        super().__init__()

        self.token_embedding = nn.Embedding(vocab_size, n_embed)
        self.position_embedding = nn.Embedding(block_size, n_embed)

        self.blocks = nn.Sequential(*[
            Block(n_embed, n_head, block_size)
            for _ in range(n_layer)
        ])

        self.ln = nn.LayerNorm(n_embed)
        self.lm_head = nn.Linear(n_embed, vocab_size)

    def forward(self, idx):
        B, T = idx.shape

        # Get embeddings
        tok_emb = self.token_embedding(idx)
        pos_emb = self.position_embedding(torch.arange(T, device=idx.device))

        x = tok_emb + pos_emb

        # Pass through transformer blocks
        x = self.blocks(x)

        # Final layer norm
        x = self.ln(x)

        # Project to vocabulary
        logits = self.lm_head(x)

        return logits

Stage 4: Training the Model

Configuration

First, define your hyperparameters:

# config.py

# Model architecture
vocab_size = 100     # Character-level vocabulary
block_size = 256     # Context length
n_embed = 384        # Embedding dimension
n_head = 6           # Number of attention heads
n_layer = 8          # Number of transformer layers

# Training
batch_size = 64
learning_rate = 3e-4
max_iters = 10000
eval_interval = 100

# Generation
max_new_tokens = 300
temperature = 0.8

Training Loop

# train.py

import torch
import torch.nn.functional as F
from config import *
from tokenizer import CharTokenizer
from data import TextDataset
from model import GPT

# Load data
with open('data/input.txt', 'r', encoding='utf-8') as f:
    text = f.read()

# Create tokenizer
tokenizer = CharTokenizer(text)
vocab_size = tokenizer.vocab_size

# Create dataset
data = tokenizer.encode(text)
dataset = TextDataset(data, block_size)

# Initialize model
model = GPT(vocab_size, n_embed, n_head, n_layer, block_size)

# Move to GPU if available
device = 'mps' if torch.backends.mps.is_available() else 'cpu'
model = model.to(device)

# Optimizer
optimizer = torch.optim.AdamW(model.parameters(), lr=learning_rate)

# Training loop
for step in range(max_iters):
    # Get batch
    xb, yb = dataset.get_batch(batch_size)
    xb, yb = xb.to(device), yb.to(device)

    # Forward pass
    logits = model(xb)

    # Compute loss
    loss = F.cross_entropy(
        logits.view(-1, vocab_size),
        yb.view(-1)
    )

    # Backward pass
    optimizer.zero_grad()
    loss.backward()
    optimizer.step()

    # Log progress
    if step % eval_interval == 0:
        print(f"Step {step}: loss = {loss.item():.4f}")

# Save model
torch.save(model.state_dict(), 'model.pt')

Stage 5: Generating Text

# generate.py

import torch
from config import *
from tokenizer import CharTokenizer
from model import GPT

def generate(model, tokenizer, start_text, max_new_tokens, temperature=0.8):
    """Generate text from a starting prompt"""
    model.eval()

    # Encode the start text
    idx = torch.tensor([tokenizer.encode(start_text)], dtype=torch.long)
    idx = idx.to(next(model.parameters()).device)

    for _ in range(max_new_tokens):
        # Get predictions
        with torch.no_grad():
            logits = model(idx)
            logits = logits[:, -1, :]  # Get last token's logits

            # Apply temperature
            logits = logits / temperature

            # Convert to probabilities
            probs = logits.softmax(dim=-1)

            # Sample from the distribution
            next_token = torch.multinomial(probs, num_samples=1)

            # Append to sequence
            idx = torch.cat([idx, next_token], dim=1)

    # Decode and return
    generated = tokenizer.decode(idx[0].tolist())
    return generated

# Load model
model = GPT(vocab_size, n_embed, n_head, n_layer, block_size)
model.load_state_dict(torch.load('model.pt'))
model.to(device)

# Generate text
prompt = "Once upon a time"
generated_text = generate(
    model,
    tokenizer,
    prompt,
    max_new_tokens=300,
    temperature=0.8
)
print(generated_text)

Advanced Sampling: Top-K and Top-P

def generate_with_sampling(model, tokenizer, start_text, max_new_tokens, 
                          temperature=0.8, top_k=None, top_p=None):
    """Generate with Top-K or Nucleus (Top-P) sampling"""
    model.eval()

    idx = torch.tensor([tokenizer.encode(start_text)], dtype=torch.long)
    idx = idx.to(next(model.parameters()).device)

    for _ in range(max_new_tokens):
        with torch.no_grad():
            logits = model(idx)
            logits = logits[:, -1, :] / temperature

            # Top-K filtering
            if top_k is not None:
                v, _ = torch.topk(logits, min(top_k, logits.size(-1)))
                logits[logits < v[:, [-1]]] = float('-inf')

            # Top-P (nucleus) filtering
            if top_p is not None:
                sorted_logits, sorted_indices = torch.sort(logits, descending=True)
                cumulative_probs = torch.cumsum(F.softmax(sorted_logits, dim=-1), dim=-1)

                # Remove tokens with cumulative probability above the threshold
                sorted_indices_to_remove = cumulative_probs > top_p
                sorted_indices_to_remove[..., 1:] = sorted_indices_to_remove[..., :-1].clone()
                sorted_indices_to_remove[..., 0] = 0

                indices_to_remove = sorted_indices_to_remove.scatter(1, sorted_indices, sorted_indices_to_remove)
                logits[indices_to_remove] = float('-inf')

            probs = F.softmax(logits, dim=-1)
            next_token = torch.multinomial(probs, num_samples=1)
            idx = torch.cat([idx, next_token], dim=1)

    return tokenizer.decode(idx[0].tolist())

Configuration for a ~10M Parameter Model

A compact GPT configuration that lands near 10 million parameters:

Hyperparameter	Value
Vocabulary	Character-level (~80-200 chars)
Context Length (`block_size`)	256
Embedding Dimension (`n_embed`)	384
Transformer Layers (`n_layer`)	8
Attention Heads (`n_head`)	6
Feed-Forward Hidden Size	1536 (4× embedding)
Batch Size	64
Learning Rate	3e-4
Optimizer	AdamW
Parameters	~10 Million

Performance Benchmarks

With the MPS backend enabled, training a 10M parameter model on a MacBook is surprisingly fast:

M1 Max: ~7.7x faster than CPU training
M2 Pro: A 10M model shows promising results in ~1 hour
M3 Pro: Can train the same model in under an hour

# Move model to MPS
device = torch.device('mps' if torch.backends.mps.is_available() else 'cpu')
model = model.to(device)

# Everything else remains the same!

Where to Go Next

Once you've built a working GPT from scratch, you'll have the foundation to explore more advanced ideas:

Tokenization Improvements

Byte Pair Encoding (BPE): More efficient than character-level
SentencePiece: Handles unicode and multiple languages
Byte-level tokenization: Preserves raw bytes

Architecture Enhancements

Rotary Positional Embeddings (RoPE): Better relative positioning
FlashAttention: Faster attention computation
KV Caching: Faster inference
RMSNorm: Faster alternative to LayerNorm
Weight Tying: Share embeddings between input and output

Training Optimizations

Mixed Precision Training (FP16/BF16)
Gradient Checkpointing
Learning Rate Schedules: Warmup + cosine decay
Gradient Accumulation

Advanced Techniques

LoRA and QLoRA: Efficient fine-tuning
RLHF: Reinforcement Learning from Human Feedback
RAG: Retrieval-Augmented Generation
Mixture of Experts (MoE)

Suggested Learning Roadmap

Build the character tokenizer ✓
Implement batch creation and next-token prediction ✓
Add token and positional embeddings ✓
Implement masked self-attention ✓
Extend to multi-head attention ✓
Add feed-forward network, layer norm, residual connections ✓
Stack multiple transformer blocks ✓
Train using cross-entropy loss and AdamW ✓
Implement autoregressive generation with sampling ✓
Next Steps:
- Add dropout for regularization
- Implement learning rate scheduling
- Add validation metrics and early stopping
- Experiment with different model sizes
- Try BPE tokenization

Example Training Data Sources

For your first model, start with a single text corpus:

Public domain books: Project Gutenberg
Shakespeare plays: Complete works
Wikipedia extracts: First few MB of text
TinyStories: Small story dataset
Code datasets: For building a code model

A few hundred kilobytes of clean text is enough to produce recognizable language patterns with a 10M parameter model.

Final Thoughts

The gap between using Generative AI and truly understanding it is smaller than it appears. Every modern language model—from compact open-source models to frontier-scale systems—relies on the same core ideas: tokenization, embeddings, self-attention, feed-forward networks, normalization, residual connections, and next-token prediction.

Building a small GPT model from scratch won't produce ChatGPT-level intelligence, but it will give you something even more valuable: intuition. You'll understand why Transformers work, how they learn, and where the opportunities lie for optimization, fine-tuning, and innovation.

Scaleable Multifaceted File System Search Architecture

Ankit Arora — Wed, 01 Jul 2026 05:38:41 +0000

To achieve an efficient "fast file lookup search, then deep content graph indexing," the best approach is a layered architecture including knowledge graph construction:

Layer 1 (Instant Lookup): Uses native OS commands to find files by name/metadata in milliseconds.
Layer 2 (Content Extraction): Parses the found files to extract plain text.
Layer 3 (Knowledge Memory): Stores extracted text as vectors and graph relationships, with built-in TTL (Time-To-Live) for automatic expiration.

Complete technical blueprint and architecture design

1. Fast File Lookup (Using OS Native Commands)

To find files instantly without scanning the entire hard drive, you must tap into the OS's pre-built indexes. Do not use os.walk() for the initial lookup.

OS	Command / SDK	How it works
Windows	Everything SDK / `es.exe`	Accesses the USN Journal and MFT (Master File Table). Searches are near-instantaneous (<100ms for millions of files).
macOS	`mdfind`	Uses the Spotlight metadata index. Run `mdfind -name "keyword"` for filenames, or `mdfind "kMDItemContentType == 'pdf'"` for types.
Linux	`plocate` / `mlocate`	Uses a pre-built database updated by `updatedb`. `plocate` is extremely fast and uses minimal I/O.

Python Implementation Snippet:

import subprocess
import platform

def os_file_lookup(query, file_type=None):
    system = platform.system()
    if system == "Windows":
        # Assuming Everything is installed
        cmd = ["es.exe", "-n", "100", query] 
    elif system == "Darwin": # macOS
        cmd = ["mdfind", "-name", query]
    else: # Linux
        cmd = ["plocate", query]

    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.stdout.splitlines()

2. Content Extraction (Parsing PDF, Word, Excel, etc.)

Once you have the file paths from Layer 1, you pass them to an extraction engine. For a unified interface, use these Python libraries:

all2txt or doc-master: Provides a single parse(file_path) function that handles .docx, .xlsx, .pptx, .pdf, .odt, .epub, and .pages. It automatically chooses the right parser behind the scenes.
fscan: A multi-threaded Python search tool. You can borrow its extractor logic for speed.
For more improved performance in C++ *: Use *libpoppler (PDF), libxml2 (DOCX/XLSX are just ZIPs of XML), and xlsxioread (Excel).

3. Knowledge Graph + Vector Memory (With TTL)

To store this as "memory" and remove it after disuse or max capacity, you need a database that supports Graph relationships, Vector embeddings, and TTL (Time-To-Live) indices.

Tool	Why it fits your requirement
Grafeo (with LlamaIndex)	An embedded graph database (single `.db` file). It natively supports Vector Search (for semantic context) and GQL (Graph Query Language). Perfect for a single installable software.
Cognee	Specifically built as an "AI Memory" engine. It automates the extraction of entities and relationships from your extracted text, builds a graph, and automatically prunes (deletes) old data based on usage frequency.
SQLite + sqlite-vec + TTL	A simpler DIY approach: Store chunks of text in SQLite, enable the `sqlite-vec` extension for similarity search, and add a `created_at` column with an index. Run a background scheduler every hour to `DELETE FROM memory WHERE created_at < datetime('now', '-7 days')`.

Memory Management (Your "Remove after unused or max increased" requirement):

Use a LRU (Least Recently Used) cache pattern on the graph nodes.
Store a last_accessed timestamp for every entity. When the database exceeds your defined size limit (e.g., 500MB), run a cleanup job that deletes the oldest 20% of nodes.
Alternatively, assign a "Hotness" score. Files opened via the chat interface get a +1 score; if a node's score drops to 0 and 30 days have passed, it is purged.

4. Hybrid Search Workflow (Efficient "Lookup First" Search)

Your system should not search the heavy graph database for every keystroke. Use this flow:

User types a query in the chat interface.
Fast Path: Fire the OS command (mdfind/es.exe) to get filenames matching the query. Display these immediately (under 200ms).
Parallel Deep Path: Simultaneously, send the query to the Knowledge Graph (Vector + Graph search). This takes a bit longer (1-3 seconds).
Aggregation: Show the user: "Found 15 files (OS lookup). Here are the top 3 knowledge contexts extracted from them (AI lookup)."

5. Suggested System Architecture Diagram

flowchart TD
    UI[User Chat / Editor Interface] --> Router{Query Router};

    Router -->|"Filename/Path Query"| OS_Layer[OS Lookup Layer];
    OS_Layer --> Win[Windows: Everything SDK];
    OS_Layer --> Mac[macOS: mdfind];
    OS_Layer --> Lin[Linux: plocate];
    OS_Layer -->|"Paths found"| Extractor[Content Extractor];

    Router -->|"Semantic / Context Query"| Graph_DB[Knowledge Graph Memory];
    Graph_DB --> Vec[Vector Search for Context];
    Graph_DB --> Rel[Graph Traversal for Relationships];

    Extractor --> Chunker[Text Chunker + Embedder];
    Chunker --> Graph_DB;

    subgraph Memory_Management[Automated Memory Pruning]
        TTL[TTL Scheduler] -->|"Delete old/unused nodes"| Graph_DB;
        Size_Monitor[Size Monitor] -->|"If > 500MB, purge oldest"| Graph_DB;
    end

    OS_Layer --> Aggregator[Result Aggregator];
    Graph_DB --> Aggregator;
    Aggregator --> UI;

6. Roadmap for the Installable Text Editor + Chat Solution

Since you want to eventually build this into a downloadable app in (C++ or Python), here is the recommended tech stack:

Backend Core (Python): Use FastAPI or Starlette to wrap your search and graph logic into a local REST API or WebSocket server.
Frontend UI (Cross-platform): Use Tauri (Rust + HTML/JS) or Electron for the text editor with a chat sidebar. Tauri is lighter, but Electron is easier to integrate Python via child_process.
Packaging: Use PyInstaller (for Python) or CPack (for C++) to bundle the Everything SDK (Windows DLLs) and the database into a single .exe / .dmg / .deb.

Why choose this approach?

Speed: OS commands give you file results in < 100ms, which feels "instant" to users.
Intelligence: The Graph DB provides "contextual memory" (e.g., finding an Excel number mentioned in a PDF).
Self-maintaining: The TTL and size monitors ensure the software won't bloat your user's hard drive, automatically removing memory that is no longer relevant.

BMT-Holiday API: The Most Comprehensive Holiday Data You'll Need For Any Application

Ankit Arora — Tue, 23 Jun 2026 17:47:29 +0000

🎯 The Problem

Let's face it, most holiday APIs are incomplete, expensive, or just plain unreliable. Whether you're building a global scheduling app, planning international content, or creating a travel platform, inaccurate holiday data can break your user experience.

The market is flooded with options:

Holiday API (holidayapi.com): Charges for fresh data and limits free plans
Nager.Date: Only covers 100+ countries—missing nearly 50 countries that BMT-Holiday supports
Abstract API: Has good reviews but limited historical data access
Time and Date: Complex implementation with minimal localization support
API-Ninjas: Covers 230 countries but lacks automatic detection

Meanwhile, BMT-Holiday API gives you 150+ countries, automatic country detection, and localization—all in a single fast and efficient API.

🚀 BMT-Holiday

1️⃣ Automatic Country Detection

Most APIs require you to hardcode country codes. BMT-Holiday intelligently detects the user's location automatically—perfect for mobile apps, global websites, and multi-region platforms.

// With BMT-Holiday, country is OPTIONAL!
GET https://api-bmtdaily.koyeb.app/holidays?date=2026-12-25
// Auto-detects country and returns relevant holidays

2️⃣ Full Holiday Information, Not Just Names

Other APIs give you a holiday name and date. BMT-Holiday provides comprehensive data:

{
  "success": true,
  "user": {
    "is_holiday": true,
    "holiday_name": "Christmas Day",
    "country": "US",
    "details": {
      "type": "Public Holiday",
      "regions": ["All"],
      "observed_by": ["Federal", "State"]
    }
  }
}

3️⃣ Multiple Endpoints for Every Use Case

Endpoint	Purpose	What Others Offer
Quick Holiday Check	Instant yes/no check	Limited to single date
Upcoming Holidays	Plan ahead with details	Basic list only
Worldwide Holidays	Global view on any date	Usually missing
Year/Month/Range	Flexible timeframes	Rigid year-only queries
Compare Countries	Side-by-side holiday comparison	Non-existent!
Search Holidays	Find any holiday by name	Basic filtering only
Regions API	Region-specific holidays	Rarely supported

Bonus: The Refresh Cache endpoint ensures you always have the latest data without waiting for updates.

🔥 Features That Make Developers Choose BMT-Holiday

🌐 Localization Built-In

No more manually mapping country codes to display names. BMT-Holiday localizes holiday names and descriptions automatically based on the user's region.

⚡ Fast Response Times

With intelligent caching and optimized endpoints, BMT-Holiday delivers sub-100ms responses—critical for real-time applications.

📊 Statistical Insights

Need to know how many holidays are coming up? The stats=true parameter gives you instant analytics:

Total holidays in the period
Public vs. regional breakdown
Upcoming holiday counts

🔍 Case-Insensitive Search

Search for "Christmas" or "christmas"—BMT-Holiday finds it. Others? Not so much.

📋 Quick Comparison Table

Feature	BMT-Holiday	Holiday API	Nager.Date	Abstract API
Countries Supported	150+	230+	100+	200+
Auto Country Detection	✅	❌	❌	❌
Localization	✅	Limited	❌	❌
Compare Countries	✅	❌	❌	❌
Search Holidays	✅	Limited	❌	Limited
Region-Specific	✅	❌	✅	❌
Year/Month/Range	✅	✅	✅	Limited
Statistics	✅	❌	❌	❌
Cache Refresh	✅	❌	❌	❌
Health Check	✅	❌	❌	Limited

💻 Example Usage

Check if Today is a Holiday in India

const response = await fetch('https://api-bmtdaily.koyeb.app/holidays/check?country=IN&date=2026-06-23');
const data = await response.json();
console.log(data.is_holiday ? '🎉 Holiday!' : '📅 Working day');

Get All Upcoming Holidays in the US

const response = await fetch('https://api-bmtdaily.koyeb.app/holidays/upcoming?country=US&limit=20&details=true');
const data = await response.json();
data.holidays.forEach(h => console.log(`${h.date}: ${h.name}`));

Compare Holidays Between Two Countries

const response = await fetch('https://api-bmtdaily.koyeb.app/holidays/compare?country=IN&compare_country=US&date=2026-06-23');
const data = await response.json();
console.log(data.comparison); // Full side-by-side comparison

🏆 What Other APIs Can't Do

Automatic Detection: BMT-Holiday knows where your users are—others don't.
Compare Mode: Plan team meetings across time zones with country comparison.
Regional Precision: Get holidays specific to states, provinces, or regions.
Search Intelligence: Find any holiday even if you don't know the exact name.
Real-Time Updates: Refresh cache instantly when data changes.

🚀 Production-Ready Features

Health Check Endpoint

Monitor API status in real-time:

GET https://api-bmtdaily.koyeb.app/health

Tested & Verified

All endpoints include built-in Postman tests and validation:

Status code verification
Response structure validation
Data integrity checks

Developer-Friendly

Detailed, predictable JSON responses
Comprehensive error handling
Detailed documentation
Postman collection ready

Features

✅ Automatic country detection (unique keyword phrase)
✅ 150+ countries (more than Nager.Date)
✅ Compare countries (unique feature no competitor offers)
✅ Built-in localization (developer-friendly)
✅ Cache refresh (enterprise-ready)
✅ Free tier (accessible to all)

Start building with BMT-Holiday.

🔗 Resources

Website: https://bmt-holidays.netlify.app/
RapidAPI: https://rapidapi.com/05.ankitarora/api/bmt-holidays/playground
GitHub: bmt-holidays

Postman schema

{
  "info": {
    "name": "🌍 BMT-Holiday API",
    "description": "Comprehensive BMT-Holiday API with 150+ countries support. Includes automatic country detection with localization.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Get Holidays (Full Info)",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has success flag\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('success');",
              "    pm.expect(jsonData.success).to.eql(true);",
              "});",
              "pm.test(\"Response has holiday data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('user');",
              "    pm.expect(jsonData.user).to.have.property('is_holiday');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays?country={{country}}&date={{date}}&stats=true&upcoming=true&limit=20",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code (auto-detected if omitted)"
            },
            {
              "key": "date",
              "value": "{{date}}",
              "description": "Date in YYYY-MM-DD format"
            },
            {
              "key": "stats",
              "value": "true",
              "description": "Include statistics"
            },
            {
              "key": "upcoming",
              "value": "true",
              "description": "Include upcoming holidays"
            },
            {
              "key": "limit",
              "value": "20",
              "description": "Number of upcoming holidays"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Quick Holiday Check",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has holiday info\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('is_holiday');",
              "    pm.expect(jsonData).to.have.property('country');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/check?country={{country}}&date={{date}}",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "check"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "date",
              "value": "{{date}}",
              "description": "Date in YYYY-MM-DD format"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Upcoming Holidays",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has upcoming holidays\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('holidays');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/upcoming?country={{country}}&limit={{limit}}&date={{date}}&details=true",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "upcoming"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "limit",
              "value": "{{limit}}",
              "description": "Number of holidays to return"
            },
            {
              "key": "date",
              "value": "{{date}}",
              "description": "Starting date"
            },
            {
              "key": "details",
              "value": "true",
              "description": "Include full details"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Worldwide Holidays",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has worldwide data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('total_holidays');",
              "    pm.expect(jsonData).to.have.property('countries_with_holidays');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/worldwide?date={{date}}&limit={{worldwideLimit}}",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "worldwide"],
          "query": [
            {
              "key": "date",
              "value": "{{date}}",
              "description": "Date to check"
            },
            {
              "key": "limit",
              "value": "{{worldwideLimit}}",
              "description": "Max countries to include"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get Year Holidays",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has year data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('total_holidays');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/year/{{year}}?country={{country}}&details=true",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "year", "{{year}}"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "details",
              "value": "true",
              "description": "Include full details"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get Month Holidays",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has month data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('total_holidays');",
              "    pm.expect(jsonData).to.have.property('month');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/month?country={{country}}&year={{year}}&month={{month}}",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "month"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "year",
              "value": "{{year}}",
              "description": "Year"
            },
            {
              "key": "month",
              "value": "{{month}}",
              "description": "Month (1-12)"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get Holidays in Range",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has range data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('total_holidays');",
              "    pm.expect(jsonData).to.have.property('range');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/range?country={{country}}&from={{fromDate}}&to={{toDate}}",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "range"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "from",
              "value": "{{fromDate}}",
              "description": "Start date (YYYY-MM-DD)"
            },
            {
              "key": "to",
              "value": "{{toDate}}",
              "description": "End date (YYYY-MM-DD)"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Compare Countries",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has comparison data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('comparison');",
              "    pm.expect(jsonData.comparison).to.have.property('country1');",
              "    pm.expect(jsonData.comparison).to.have.property('country2');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/compare?country={{country}}&compare_country={{compareCountry}}&date={{date}}",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "compare"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "First country"
            },
            {
              "key": "compare_country",
              "value": "{{compareCountry}}",
              "description": "Second country"
            },
            {
              "key": "date",
              "value": "{{date}}",
              "description": "Date to compare"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Search Holidays",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has search results\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('results');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/search?q={{searchQuery}}&country={{country}}&year={{year}}&caseSensitive=false",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "search"],
          "query": [
            {
              "key": "q",
              "value": "{{searchQuery}}",
              "description": "Search term (min 2 chars)"
            },
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "year",
              "value": "{{year}}",
              "description": "Year to search"
            },
            {
              "key": "caseSensitive",
              "value": "false",
              "description": "Case sensitive search"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get Supported Countries",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has countries data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('countries');",
              "    pm.expect(jsonData).to.have.property('total_countries');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/countries",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "countries"]
        }
      },
      "response": []
    },
    {
      "name": "Get Regions",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response has regions data\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('regions');",
              "    pm.expect(jsonData).to.have.property('total_regions');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/regions?country={{country}}&year={{year}}",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "regions"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "year",
              "value": "{{year}}",
              "description": "Year"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Refresh Cache",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Response confirms cache refresh\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('message');",
              "    pm.expect(jsonData.message).to.include('refreshed');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/holidays/refresh?country={{country}}&year={{year}}",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["holidays", "refresh"],
          "query": [
            {
              "key": "country",
              "value": "{{country}}",
              "description": "ISO country code"
            },
            {
              "key": "year",
              "value": "{{year}}",
              "description": "Year"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Health Check",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test(\"Status code is 200\", function() {",
              "    pm.response.to.have.status(200);",
              "});",
              "pm.test(\"Service is healthy\", function() {",
              "    var jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('status');",
              "    pm.expect(jsonData.status).to.eql('healthy');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "https://api-bmtdaily.koyeb.app/health",
          "protocol": "https",
          "host": ["api-bmtdaily", "koyeb", "app"],
          "path": ["health"]
        }
      },
      "response": []
    }
  ],
  "variable": [
    {
      "key": "country",
      "value": "IN",
      "type": "string"
    },
    {
      "key": "date",
      "value": "2026-06-21",
      "type": "string"
    },
    {
      "key": "year",
      "value": "2026",
      "type": "string"
    },
    {
      "key": "month",
      "value": "7",
      "type": "string"
    },
    {
      "key": "limit",
      "value": "10",
      "type": "string"
    },
    {
      "key": "worldwideLimit",
      "value": "10",
      "type": "string"
    },
    {
      "key": "compareCountry",
      "value": "US",
      "type": "string"
    },
    {
      "key": "searchQuery",
      "value": "Columbus",
      "type": "string"
    },
    {
      "key": "fromDate",
      "value": "2026-06-01",
      "type": "string"
    },
    {
      "key": "toDate",
      "value": "2026-06-30",
      "type": "string"
    }
  ]
}

BMT-Holiday API: The Most Comprehensive Holiday Data Solution | 150+ Countries | Automatic Detection | Built-in Localization