Nepali Calendar Data API

A machine-readable Nepali calendar (Bikram Sambat) dataset and high-performance API. This project provides automated scraping, structured data storage, and a RESTful interface for calendar data from 1992 BS to the present.

---

🚀 Live API

The API is deployed and publicly accessible:
https://api-nepalicalendar.leapcell.app

Interactive documentation (Swagger UI) is available at:
/docs

---

✨ Features

• Accurate Mapping: Reliable BS to AD date conversion.
• Rich Metadata: Includes Tithi, religious festivals, and public holidays.
• Auspicious Dates: Monthly data for Marriage and Bratabandha.
• Dual Format Storage: Optimized for both bulk (yearly) and granular (monthly) access.
• High Performance: Built with FastAPI and uv for minimal overhead.
• Zero-Touch Updates: Automated daily scraping via GitHub Actions with dynamic year calculation.

---

🛠️ Getting Started

Prerequisites

• Python 3.13+
• uv (highly recommended for dependency management)

Installation

1. Clone the repository:

   git clone https://github.com/S4NKALP/nepali-calendar-api.git
   cd nepali-calendar-api

2. Install dependencies:

   uv sync

Running the API Locally

uv run uvicorn app:app --reload

The server will start at http://localhost:8000.

---

📊 Data Structure

Dataset resides in the /data directory:

• Aggregated Yearly: data/<year>.json (Full 12-month payload)
• Modular Monthly: data/<year>/<month>.json (Lightweight monthly payload)

Sample Output Format

{
  "metadata": {
    "np": "बैशाख २०८२",
    "en": "Apr/May 2025"
  },
  "days": [
    {
      "d": 2,
      "n": "१",
      "e": "14",
      "t": "प्रतिपदा",
      "f": "navavarsha 2082",
      "h": true
    }
  ],
  "holiFest": ["navavarsha 2082..."],
  "marriage": ["..."],
  "bratabandha": ["..."]
}

---

🕵️ Scraper Usage

The scraper is the core engine for dataset expansion.

# Scrape specific year
uv run scraper.py 2082

# Scrape range
uv run scraper.py 2070 2085

# Format-specific flags
uv run scraper.py 2082 --single json   # Aggregated only
uv run scraper.py 2082 --dir format    # Monthly files only

---

🤖 CI/CD & Automation

This project uses GitHub Actions (.github/workflows/scrape.yml) to keep the data fresh.

• Frequency: Runs daily at 00:00 UTC.
• Intelligence: Automatically calculates the current BS year and updates folders.
• Manual Control: Supports workflow_dispatch to manually scrape any year via the GitHub UI.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---