134 lines
3.7 KiB
Markdown
134 lines
3.7 KiB
Markdown
# Nepali Calendar Data API
|
|
|
|
[](https://www.python.org/downloads/release/python-3130/)
|
|
[](https://fastapi.tiangolo.com/)
|
|
[](https://github.com/astral-sh/uv)
|
|
[](https://api-nepalicalendar.leapcell.app)
|
|
|
|
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](https://api-nepalicalendar.leapcell.app)**
|
|
|
|
Interactive documentation (Swagger UI) is available at:
|
|
**[/docs](https://api-nepalicalendar.leapcell.app/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](https://github.com/astral-sh/uv)** (highly recommended for dependency management)
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://github.com/S4NKALP/nepali-calendar-api.git
|
|
cd nepali-calendar-api
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
### Running the API Locally
|
|
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
---
|
|
|