An open-source API that provides accurate Sri Lankan holiday data, offering a comprehensive list of public holidays in multiple file formats for easy integration into your applications.
Holidays are updated every year and currently contains holidays starting from 2021. All records are validated through manual inspection, No AI or scripts!
| Project/App | Description |
|---|---|
| Simple-Calendar | A simple calendar with events, tasks, customizable colors, widgets and no ads. |
*Simple-Calendar has been deprecated and moved to Fossify: https://github.com/FossifyOrg/Calendar
- Reliable and accurate local data (see Data Sources)
- Open-source and free to use
- Updated every year
- Available as both API and downloadable files
- Holiday categorizations (Public, Bank, Mercantile, Poya, etc.)
The API is live at https://srilanka-holidays.vercel.app and ready for public use! Built with FastAPI, it offers a modern, developer-friendly experience with robust features.
🔺 IMPORTANT: Version v1.1.0 introduces breaking changes with partial backward compatibility.
-
/api/v1/statusnow requires authentication. -
/api/v1/holiday_infonow returns holidays for a given day as an array.
Please refer to the release notes for detailed information.
- Holiday Lists: Retrieve holidays for any year or filter by month and type (public, poya, mercantile, bank).
- Date Checker: Check if a specific date is a holiday with detailed info (e.g., holiday name, type).
- API Key Authentication: Secure access using
X-API-Keyheader. - Redis Caching: Lightning-fast responses with cached data.
- Interactive Docs: Explore endpoints at
/docsor/redoc. - Self-Host: Deploy on your favorite platform
-
Obtain an API Key:
- Contact us to request a free API key
- Include your key in every request:
X-API-Key: your-key.
-
Explore Endpoints:
-
List Holidays:
GET /api/v1/holidays?year=2025(optional:month,type,format=simple|full)Example:
curl -H "X-API-Key: your-key" https://srilanka-holidays.vercel.app/api/v1/holidays?year=2025 -
Check Date:
GET /api/v1/check_holiday?year=2025&month=5&day=1Example:
`curl -H "X-API-Key: your-key" srilanka-holidays.vercel.app/api/v1/check_holiday?year=2025&month=5&day=1
-
-
Read the Docs:
- Visit https://srilanka-holidays.vercel.app/docs for interactive Swagger UI or https://srilanka-holidays.vercel.app/redoc for ReDoc.
-
Homepage:
- Check out https://srilanka-holidays.vercel.app for an overview and request a free API key.
Click here to read more..
To test or contribute to the API, run it locally:
-
Clone the Repository:
git clone https://github.com/Dilshan-H/srilanka-holidays.git cd srilanka-holidays -
Set Up a Virtual Environment:
python -m venv venv source venv/bin/activate # On Windows:venv\Scripts\activate
-
Install Dependencies:
pip install -r requirements.txt
-
Setup REDIS database:
Visit Redis Cloud and login to your account. Then make a new database and make a note of your db's REDIS CONNECT URL.
OR
If you're using Vercel, check
Storagedashboard to connect Redis directly. -
Configure Environment Variables:
Create a .env file with your variables. (Please note that API_KEYS mention here will contain FALLBACK API KEYS just in case if REDIS fails)
REDIS_HOST=your-redis-host.com REDIS_PORT=redis-port-number REDIS_PASSWORD=redis-password REDIS_USERNAME=redis-username API_KEYS=test-key-123,prod-key-456
-
Store API KEYS in REDIS Use
Redis Insightto quickly store data as JSON. Add a new KEY with JSON as the data type. Name the key asAPI_KEYS_V2(you can use other names, but remember to update it in your code as well.){ "api_keys": [ { "key": "API_KEY", "created": 1749841807, "username": "USERNAME", "description": "DESCRIPTION" } ] } -
Start app with:
fastapi dev app.py
From here you can download the list of holidays in several file formats and integrate with your applications directly without using the API.
This section provides tentative holiday data files, which are available for early implementation. While these datasets are sourced from official channels, they remain incomplete as the finalized holiday data is typically released by the government in the final months of the year. Currently, these holidays are offered only as downloadable ICS files, and the data in this section is not yet integrated into the API.
-
Year 2027 Tentative Holiday Data
Upcoming data will be posted here after verification.
Notes: [Additional details/comments]
Source: [Data sources]
These files are generated automatically from the iCalendar files and are available in JSON, CSV, and XML formats.
If you're unable to download individual files, please visit the releases page here to download specific versions or download the source code as a zip file, which you can extract to find the data inside the respective folders.
All the data is collected from verified and reliable sources within the Sri Lankan government. This usually involves the Ministry of Home Affairs, Department of Government Printing and the Gazette papers.
- State Ministry of Home Affairs, Sri Lanka - https://moha.gov.lk/
- Department of Government Printing, Sri Lanka - http://www.documents.gov.lk/
Holidays are divided into several categories based on the default categorization method of the Sri Lankan government.
The following categories are used:
- Public Holidays
- Poya Holidays
- Bank Holidays
- Mercantile Holidays
Got an idea? Found a bug? Feel free to open an issue or submit a pull request.
Fork the repository, make your changes and submit a pull request. It's that much easy! If you're not sure how to do that, here's a guide.
The MIT License
This program is free software: you can redistribute it and/or modify it under the terms of the MIT License. See the LICENSE file for more details. Attribution is required by leaving the author name and license info intact.