sankalp
9cb6ade8a6
- Switch to async lifespans, eager in‑memory caching of calendar data, and ORJSON responses for reduced latency. - Add structured logging and GZIP middleware, enforce year bounds and directory existence. - Replace json module with orjson, use pathlib and TypedDict aliases, and implement typed argument parsing with explicit error handling. - Remove unused test.py and refactor scraper CLI to accept argv via function injection, simplify input mode logic. - Preserve backward defaults (produce both single JSON and directory output) while exposing explicit flags via argparse. This refactor improves scalability on low‑resources servers, adds robustness checks, and clarifies the command‑line interface for future extensions.
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
uvfor 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
-
Clone the repository:
git clone https://github.com/S4NKALP/nepali-calendar-api.git cd nepali-calendar-api -
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_dispatchto 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.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request