API Documentation — Nepali Date Converter

The Nepali Date Conversion API provides a simple and reliable way to convert dates between the Bikram Sambat (BS) calendar and the Gregorian (AD) calendar. This API is perfect for applications that need to handle Nepali dates accurately.

Features for Developers & Coders

• ✅ Convert AD (Gregorian) to BS (Bikram Sambat) dates
• ✅ Convert BS (Bikram Sambat) to AD (Gregorian) dates
• ✅ Get today's date in both BS and AD formats
• ✅ Calculate exact age from BS or AD birth dates
• ✅ Today's date widget (embeddable in 3 sizes)
• ✅ RESTful API with JSON responses
• ✅ GET endpoints - no authentication required
• ✅ CORS enabled for browser/web applications
• ✅ Iframe widgets for easy embedding
• ✅ Perfect for ChatGPT and AI model integration
• ✅ Comprehensive error handling
• ✅ Works with all programming languages

Perfect for AI Applications

This API is designed to be easily discoverable and usable by AI models like ChatGPT, Claude, and other AI coders. The endpoints are intuitive, responses are consistent, and no API keys are required.

Rate Limits

Currently, there are no rate limits imposed on the API. However, please use the API responsibly and avoid excessive requests.

No authentication is required to use this API. All endpoints are publicly accessible.

All endpoints return JSON responses. The API supports GET methods for date conversion.

GET /api/bs-to-ad/2080/1/1

{
  "success": true,
  "input": {
    "year": 2080,
    "month": 1,
    "day": 1,
    "type": "BS"
  },
  "result": {
    "year": 2023,
    "month": 4,
    "day": 13,
    "type": "AD"
  }
}

GET /api/todaydate

{
  "success": true,
  "timestamp": "2026-01-07T14:30:45.123456",
  "ad": {
    "year": 2026,
    "month": 1,
    "day": 7,
    "month_name": "January",
    "day_name": "Wednesday",
    "formatted": "2026-01-07",
    "full_date": "Wednesday, January 7, 2026"
  },
  "bs": {
    "year": 2082,
    "month": 9,
    "day": 23,
    "month_name": "पौष",
    "day_name": "बुधवार",
    "formatted": "2082-09-23",
    "full_date": "बुधवार, पौष 23, 2082"
  },
  "time": {
    "hour": 14,
    "minute": 30,
    "second": 45,
    "formatted": "14:30:45"
  }
}

GET /api/calculateage/bs/2081/2/23

{
  "success": true,
  "input_type": "BS",
  "birth_date": {
    "bs": {"year": 2081, "month": 2, "day": 23, "formatted": "2081-02-23"},
    "ad": {"year": 2024, "month": 6, "day": 6, "formatted": "2024-06-06"},
    "day_of_week": "Thursday"
  },
  "current_date": {
    "bs": {"year": 2082, "month": 9, "day": 23, "formatted": "2082-09-23"},
    "ad": {"year": 2026, "month": 1, "day": 7, "formatted": "2026-01-07"}
  },
  "age": {
    "years": 1,
    "months": 7,
    "days": 1,
    "formatted": "1 years, 7 months, 1 days"
  },
  "totals": {
    "days": 580,
    "weeks": 82,
    "months": 19,
    "hours": 13920,
    "minutes": 835200
  }
}

GET /api/calculateage/ad/2024/6/6

{
  "success": true,
  "input_type": "AD",
  "birth_date": {
    "ad": {"year": 2024, "month": 6, "day": 6, "formatted": "2024-06-06"},
    "bs": {"year": 2081, "month": 2, "day": 23, "formatted": "2081-02-23"},
    "day_of_week": "Thursday"
  },
  "age": {
    "years": 1,
    "months": 7,
    "days": 1,
    "formatted": "1 years, 7 months, 1 days"
  },
  "totals": {
    "days": 580,
    "weeks": 82,
    "months": 19,
    "hours": 13920,
    "minutes": 835200
  }
}

GET /api/ad-to-bs/2023/4/13

{
  "success": true,
  "input": {
    "year": 2023,
    "month": 4,
    "day": 13,
    "type": "AD"
  },
  "result": {
    "year": 2080,
    "month": 1,
    "day": 1,
    "type": "BS"
  }
}

Choose a language to see how to call the GET endpoints.

# BS to AD
curl https://sudhanparajuli.com.np/api/bs-to-ad/2080/1/1

# AD to BS
curl https://sudhanparajuli.com.np/api/ad-to-bs/2023/4/13

// BS to AD
fetch('https://sudhanparajuli.com.np/api/bs-to-ad/2080/1/1')
  .then(r => r.json())
  .then(console.log);

// AD to BS
fetch('https://sudhanparajuli.com.np/api/ad-to-bs/2023/4/13')
  .then(r => r.json())
  .then(console.log);

import requests

# BS to AD
print(requests.get('https://sudhanparajuli.com.np/api/bs-to-ad/2080/1/1').json())

# AD to BS
print(requests.get('https://sudhanparajuli.com.np/api/ad-to-bs/2023/4/13').json())

{
  "endpoints": {
    "bs_to_ad": "/api/bs-to-ad/{year}/{month}/{day}",
    "ad_to_bs": "/api/ad-to-bs/{year}/{month}/{day}"
  }
}

The API uses standard HTTP status codes to indicate success or failure of requests.

HTTP Status Codes

Error Response Format

{
  "error": "Error message description"
}

Common Error Messages

• "No JSON data provided" - POST request missing JSON body
• "Missing required fields. Provide 'type', 'year', 'month', and 'day'." - Missing required parameters
• "Invalid date type. Use 'BS_to_AD' or 'AD_to_BS'." - Invalid conversion type
• "Invalid date values: [error details]" - Invalid date format or values
• "Date conversion failed" - Internal conversion error

If you have any questions, issues, or suggestions regarding the API, please feel free to reach out:

• GitHub: @SudhanParajuli
• LinkedIn: Sudhan Parajuli
• Twitter: @sudhanparajuli0