docs(root): expand README with API details and usage instructions

2026-01-10 00:21:51 +05:45
1 parent fd07d4c341
commit 1909f8f939
@@ -1,73 +1,133 @@
-# Nepali Calendar Data
+# Nepali Calendar Data API

-Machine-readable Nepali calendar dataset and scraper covering 1992 BS to the present.
+[![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/release/python-3130/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.0+-009688.svg)](https://fastapi.tiangolo.com/)
+[![Built with uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Leapcell Deployment](https://img.shields.io/badge/Deploy-Leapcell-000?style=flat&logo=leapcell)](https://api-nepalicalendar.leapcell.app)

-## Features
+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.

- Accurate Nepali (BS) to English (AD) date mapping
- Detailed Tithi information
- Religious festivals and public holidays
- Auspicious monthly dates for Marriage and Bratabandha
- Automated scraper for continuous data updates
+---

-## Data Structure
+## 🚀 Live API

-The dataset is organized in the `data/` directory and is available in two formats:
+The API is deployed and publicly accessible:  
+**[https://api-nepalicalendar.leapcell.app](https://api-nepalicalendar.leapcell.app)**

-1. **Aggregated Yearly Data**: `data/<year>.json`
-   - A single JSON file containing all 12 months for a specific year.
-2. **Individual Monthly Data**: `data/<year>/<month>.json`
-   - Modular files for granular data access.
+Interactive documentation (Swagger UI) is available at:  
+**[/docs](https://api-nepalicalendar.leapcell.app/docs)**

-## Scraper Usage
+---

-The repository includes a Python-based scraper that uses `uv` for dependency management and performance.
+## ✨ 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

-Ensure you have `uv` installed on your system.
+- **Python 3.13+**
+- **[uv](https://github.com/astral-sh/uv)** (highly recommended for dependency management)

-### Basic Commands
+### Installation

-Generate data for a single year or a range (produces both formats by default):
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/S4NKALP/nepali-calendar-api.git
+   cd nepali-calendar-api
+   ```

-```bash
-uv run scraper.py 2082
-uv run scraper.py 2077 2085
-```
+2. Install dependencies:
+   ```bash
+   uv sync
+   ```

-### Advanced Configuration
-
-Use flags to control the output format:
-
- **Generate Single JSON only**:
-  ```bash
-  uv run scraper.py 2082 --single json
-  ```
-
- **Generate Directory Format (Monthly Files) only**:
-  ```bash
-  uv run scraper.py 2082 --dir format
-  ```
-
-## API Server
-
-The repository includes a FastAPI-based server to serve the scrapped data.
-
-### Running the API
+### Running the API Locally

 ```bash
 uv run uvicorn app:app --reload
 ```
+The server will start at `http://localhost:8000`.

-The API will be available at `http://localhost:8000`.
+---

-### API Endpoints
+## 📊 Data Structure

- `GET /calendar/{year}`: Returns the aggregated yearly calendar data.
- `GET /calendar/{year}/{month}`: Returns the individual monthly calendar data.
- `GET /docs`: Interactive API documentation (Swagger UI).
+Dataset resides in the `/data` directory:

-## Maintenance
+- **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
+
+---

-This repository is actively maintained. New calendar data is added as it becomes available.