Skip to content

janmir/tgif-jp

Repository files navigation

🍁🗾🏯Japanese Holiday API

🗻Overview

Web api for listing all Japanese Holidays of the current year and Checking if a certain date is a holiday. Holidays are based on holiday listing sites like publicholidays.jp. In this release I have provided at least 2 sources. Data is periodically updated (Atleast once a month). Okay now let's 🚄.

🗼Getting Started

You don't need to clone the source to use the api, it is already publicly available via this url: https://api.janmir.me/holiday. Please refer to Query section below for more details about api usage.

:octocat:Query

Request must be in REST-GET format. Request payload body is defined below.

{
    "action": "list",
    "format": "M/dd, D",
    "date": "Mar-15"
}

Note: This is a GET request, so you can't directly use the example payload above. But don't be sad I have provided example Request-URLs below

Action

Actions determines what you want the API to do for you 😜. An usage example is provided below.

exempli gratia:
https://api.janmir.me/holiday/list
https://api.janmir.me/holiday/check
https://api.janmir.me/holiday/fetch
Action Definition
/fetch Fetches and stores holiday data from various site defined in source.yaml. I discourage using this one as it is already automatically being called once a month. Thanks! 😍
/list Lists all holidays in Japan so we can travel more! yeah!
/check Checks if a certain date is a holiday or not.
/today Checks if today is a holiday.
/tomorrow Umm should I still explain this?

Parameters

Parameters gives you the ability to pass data to the api. And also to customize the response it sends back.

exempli gratia:
https://api.janmir.me/holiday/list?format=M/dd-%3ED
https://api.janmir.me/holiday/check?date=Mar-15
Parameter Applicable Definition
?format /list Fetches and stores holiday data from various site defined in source.yaml. Available format flags are; 'M' - Month(String - e.g. Jan, Feb, etc.), 'W' - Week(String - e.g. Mon, Tue, etc.), 'd' - Day(Number - 'dd' with padding), 'D' - Description
Example:
M/dd->D = Jan/01->New Year's Day
M/d,W,D = Jan/1,Sun,New Year's Day
?date /check The date to check, strictly should be in M-dd format.

Responses

Expected responses are in valid JSON format.

Action - Fetch https://api.janmir.me/holiday/fetch

{
    "result": true,
    "data": {
        "performance": {
            "start": 1899955.510722,
            "end": 1902836.063255,
            "execution": 2880.55
        },
        "ls": [
            "1,Sun,Jan,New Year's Day",
            "2,Mon,Jan,New Year Holiday",
            "9,Mon,Jan,Coming of Age Day",
            "11,Sat,Feb,National Foundation Day",
            "20,Mon,Mar,Vernal Equinox Day",
        ]
    }
}
Key Type Definition
result bool Result of the API request.
data Object Contains parsed and performance data.
performance Object Contains performance data.
start float Start of execution.
end float End of execution.
execution float Time took to perform the action.
ls Array List of stored holiday.

Action - List https://api.janmir.me/holiday/list?format=M/dd-%3ED

{
    "result": true,
    "holidays": [
        "Jan/01->New Year's Day",
        "Jan/02->New Year Holiday",
        "Jan/09->Coming of Age Day",
        "Feb/11->National Foundation Day",
        "Mar/20->Vernal Equinox Day"
    ],
    "execution": 0100.0010
}
Key Type Definition
result bool Result of the API request.
holidays Array Lists of all holidays.
execution float Time took to perform the action.

Action - Check https://api.janmir.me/holiday/check?date=Mar-15

{
    "holiday": false,
    "result": true,
    "execution": 0100.0010,
    "description": "It's my birthday!",
    "date": "Mar-15"
}
Key Type Definition
result bool Result of the API request.
holiday Array If given date is a holiday.
execution float Time took to perform the action.
description String Holiday description.
date String The date that was passed. In the case of tomorrow/today actions the corresponding date is returned.

Error Handling

If errors occurs while performing the action you asked a response JSON like the one below is sent.

{
    "result": false,
    "error": "I did nothing. Incorrect [action]?"
}
Key Type Definition
result bool Result of the API request.
error String Error Message.

🌸Versioning & Tracking

  • v0.0.1: Alpha Version but I'll still release it💩
    • Scheduled data fetch.
    • Parse web data.
    • Parsed information store.
    • Handling GET requests.
      • GET request for data fetch.
      • GET request for date checking.
      • GET request for holiday list.
    • External Documentation Page
  • v0.0.2: Alpha 2
    • Added Today.
    • Added Tomorrow.
    • Added date as a response to /check action.
    • Added description of holiday on check requests.

🐈Acknowledgements