-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
f0123a7
commit 0f933d0
Showing
3 changed files
with
124 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # Jalali Calendar Event API | ||
| This part is a PHP API which is used to implement persianholiday.site website. You can clone the project and use it on your server or use the API that is provided on the persianholiday.site website. | ||
|
|
||
| ## Note | ||
| The `perssianholiday.site` website is a free service and I do not guarantee the availability of the service. You can use the API on your server or use the SQLite file that is available in the repository. I highly recommend using the SQLite file because it is easy to use and you can use it on almost any platform and development project. Since keeping the API online is not free I do not guarantee the availability of the service. | ||
|
|
||
| ## Requirements | ||
| * PHP 8.2 or higher | ||
| * SQLite3 | ||
| * Composer | ||
|
|
||
| ## Data structure | ||
| The `JSON` data structure is like below: | ||
| ```json | ||
| { | ||
| "cause": "جشن نوروز/جشن سال نو", | ||
| "events": [ | ||
| "جشن نوروز/جشن سال نو", | ||
| "روز جهانی شادی [ 20 March ]" | ||
| ], | ||
| "day_id": "14030101", | ||
| "date": "2024-03-20", | ||
| "holiday": true | ||
| } | ||
| ``` | ||
| | Key | type | Description | example | | ||
| | ------------- |------------------|-----------------------------|----------- | | ||
| | cause | `TEXT` | The event cause the holiday | جشن نوروز/جشن سال نو | | ||
| | events | `ARRAY` | An array of events on that day | ["جشن نوروز/جشن سال نو", "روز جهانی شادی [ 20 March ]"] | | ||
| | day_id | `TEXT` | an ID for day which build with 4 digit of year + 2 digits of months and 2 digits of day | 14030101 | | ||
| | date | `DATE` | Date in format YYYY-mm-dd | 2024-03-20 | | ||
| | holiday | `BOOL` | 0 or 1 value shows it is a holiday or not | 1 | | ||
|
|
||
| <abbr title="Hyper Text Markup Language">NOTE:</abbr> If the day is not a holiday the `cause` not exists. | ||
|
|
||
|
|
||
| ## How to use | ||
| All routes respond to `GET` and `POST` requests. | ||
| ### Routes | ||
| * `/api/v1/today` : Get today's events | ||
| * `/api/v1/yesterday` : Get yesterday's events | ||
| * `/api/v1/tomorrow` : Get tomorrow's events | ||
|
|
||
| These routes return a `JSON` event according to the [data structure](#data-structure). | ||
| You can set the `raw` parameter to these routes to get just a `BOOL` 0 or 1 value that shows if the day is a holiday or not. | ||
| #### example | ||
| If you want to check if today holiday or not just send a `GET` request to `/api/v1/today` and check the response. | ||
|
|
||
| * `/api/v1/day` : Get events of a specific date | ||
| This route gets a parameter date with the format `YYYYMMDD` and response to the events of that day. | ||
| #### example | ||
| If you want to get `1402/02/26` events a request to `/api/v1/day?date=14020226` and check the response (You can send `POST` request too), | ||
|
|
||
| * `/api/v1/range` : Get events of a specific date range | ||
| This route gets two parameters `start_date` and `end_date` with the format `YYYYMMDD` and responds to the events of that range. The data range should be less than 365 days. | ||
| #### example | ||
| If you want to get events of `1402/02/26` to `1402/03/01` a request to `/api/v1/range?start_date=14020226&end_date=14020301` and check the response.(You can send `POST` request too), | ||
|
|
||
| ### persianholiday.site routes list | ||
| Description | URL | ||
| ------------- | ------------- | ||
| Today events | [https://persianholiday.site/api/v1/today](https://persianholiday.site/api/v1/today) | ||
| Is today a holiday? | [https://persianholiday.site/api/v1/today?raw](https://persianholiday.site/api/v1/today?raw) | ||
| Yesterday events | [https://persianholiday.site/api/v1/yesterday](https://persianholiday.site/api/v1/yesterday) | ||
| Is yesterday a holiday? | [https://persianholiday.site/api/v1/yesterday?raw](https://persianholiday.site/api/v1/yesterday?raw) | ||
| Today events | [https://persianholiday.site/api/v1/tomorrow](https://persianholiday.site/api/v1/tomorrow) | ||
| Is tomorrow a holiday? | [https://persianholiday.site/api/v1/tomorrow?raw](https://persianholiday.site/api/v1/tomorrow?raw) | ||
| Events of a specific date | [https://persianholiday.site/api/v1/day?date=14020226](https://persianholiday.site/api/v1/day?date=14020226) | ||
| Events of a specific date range | [https://persianholiday.site/api/v1/range?start_date=14020226&end_date=14020301](https://persianholiday.site/api/v1/range?start_date=14020226&end_date=14020301) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # Jalali Calendar Event Data Miner | ||
| This directory includes the PHP source code I used to mine event data from website time.ir. | ||
|
|
||
| ## Where does the data come from? | ||
| The data is mined from the [time.ir](https://www.time.ir) website. On this website, there is an annual event list for each year. I store `HTML` 30 years between 1370 and 1400 in the `src` directory. The `HTML` files are named with the year number. For example, the `HTML` file for the year 1399 is named `1399.html`. | ||
|
|
||
| ### Why Store HTML files? | ||
| The website has a lot of traffic and it is not a good idea to send a request to the website for each day. So I store the `HTML` files and use them to get the events. On the other hand, the website is protected by `CSRF` token and it is not a good idea to send a request to the website for each day. | ||
|
|
||
| ### Can I extend the data range? | ||
| Yes, you can. Just send a request to the website and store the `HTML` file in the `src` directory. Then run the `index.php` file to get the events. | ||
| ```php | ||
| php index.php | ||
| ``` | ||
| The `index.php` file will read the `HTML` files get the events and store them in the `persian_holiday.db` file. | ||
| Note that you need PHP `8.2` or higher and `SQLite3` to run the `index.php` file. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,41 @@ | ||
| # Jalali Calendar Event # | ||
| # Jalali Calendar Event | ||
| This project includes all Jalali calendar events from 1991 (1370-01-01) until 2051 (1430-12-29) which are mined from time.ir website. | ||
| ## Project structure | ||
| The repository includes three sections: | ||
|
|
||
| این مخزن شامل یک فایل sqlite شامل تمام رویداد ها از سال ۱۳۷۰ تا ۱۴۳۰ میباشد. | ||
| اطلاعات تعطبلات رسمی هم نیز در دیتابیس موجود میباشد. | ||
| Section | Description | ||
| ------------- | ------------- | ||
| persian_holiday.db file | This file includes all events and holidays | ||
| Api | It contains a PHP API which is used to implement persianholiday.site website. you can read API documentation from [HERE](https://github.com/samanzamani/PersianHoliday/tree/main/Api "here") | ||
| Data Miner | This directory includes the PHP source code I used to mine event data from website time.ir. You can read more about this project from [HERE](https://github.com/samanzamani/PersianHoliday/tree/main/Data%20Miner "HERE") | ||
|
|
||
| به زودی داکیومنت رو کامل می کنم. | ||
| ## How to use (Recommended) | ||
| * If you work on a real project and you want to release the project use SQLite file. | ||
| * If you work on a small development project you can use the API that is provided on the persianholiday.site website. | ||
|
|
||
| ## Why SQLite | ||
| It is easy to use and you can use it on almost any platform and development project. Plus you can easily delete the part you do not need and reduce SQL file size. You can use online tools to check the data. | ||
|
|
||
| ## Database structure | ||
| The SQL file contains two tables: `version` and `events`. | ||
|
|
||
| ### version table | ||
| This table contains one row that shows a numeric version and data range. Right now the version is 10 and data is available from 1991 (1370-01-01) until 2051 (1430-12-29). | ||
|
|
||
| ### events table | ||
| This table has all events with the below columns: | ||
|
|
||
| | Column | type | Description | example | | ||
| | ------------- | ----------- |--------------------------------------|----------- | | ||
| | day_id | `TEXT` | an ID for day which build with 4 digit of year + 2 digits of months and 2 digits of day | 14000204 | | ||
| | year | `INTEGER` | Jalali year with 4 digits | 1402 | | ||
| | month | `INTEGER` | Jalali month with 1 or 2 digits | 1 | | ||
| | day | `INTEGER` | Jalali day with 1 or 2 digits | 5 | | ||
| | event | `TEXT` | event day description | سال نو | | ||
| | is_holiday | `INTEGER` | 0 or 1 value shows it is a holiday or not | 1 | | ||
| | date | `DATE` | Date in formay YYYY-mm-dd | 2024-02-24 | | ||
|
|
||
| <abbr title="Hyper Text Markup Language">NOTE:</abbr> `day_id` is not a unique value because a day could have more than one event. | ||
|
|
||
| #### example | ||
| If you want to check if `1402/02/26` holiday or not just check if is there any row with `day_id=14020226` AND `is_holiday=1`. |