Next Japanese public holiday date via x402-paid API, part of the Gotobi Calendar suite.
What it does
The `/gotobi/holidays/next` endpoint returns the next upcoming Japanese public holiday relative to today. It is part of the Gotobi Calendar API, which is described as the only programmatic source for Japanese FX gotobi (五十日) dates, providing holiday-adjusted dates through 2099 for algorithmic trading use cases.
This specific endpoint requires no parameters — a simple GET request returns the current date, the next holiday date, the holiday name, and the number of days until that holiday. The response schema (`NextHolidayResponse`) includes fields: `today`, `next_holiday_date`, `next_holiday_name`, `days_until`, and `description`. The API is x402-gated at $0.01 USDC per call on Base. Alternative access methods include an MCP gateway, API key with free credit, or the `x402-pay` Python SDK.
The broader Gotobi Calendar API also offers endpoints for checking whether today is a gotobi date, finding the next gotobi date, listing gotobi dates for a given month, checking if today is a holiday, and listing holidays for a given month. Gotobi dates (5th, 10th, 15th, 20th, 25th, and month-end) are significant in Japanese FX markets because corporate settlements cluster on these days, often strengthening the yen. The holiday data covers Japanese public holidays and is used to shift gotobi dates when they fall on non-business days.
Capabilities
Use cases
- —Algorithmic FX trading systems that need to know when the next Japanese holiday falls to adjust gotobi settlement logic
- —Scheduling bots that need upcoming Japanese public holiday dates for calendar integration
- —Financial dashboards displaying days until the next Japanese market closure
- —Travel or HR applications needing programmatic access to Japan's national holiday schedule
Fit
Best for
- —FX traders needing holiday-adjusted gotobi dates
- —Automated systems requiring Japanese public holiday lookups
- —Agents or bots that need a simple, parameter-free next-holiday endpoint
Not for
- —Comprehensive multi-country holiday calendars
- —Historical holiday data queries (this endpoint only returns the next upcoming holiday)
- —Free/unauthenticated bulk access — each call costs $0.01 USDC
Quick start
pip install x402-pay
import x402_pay
r = x402_pay.get('https://gotobi.hugen.tokyo/gotobi/holidays/next')
print(r.json())Example
Response
{
"today": "2026-02-20",
"days_until": 3,
"description": "The next Japanese public holiday is Emperor's Birthday on 2026-02-23, 3 days from now.",
"next_holiday_date": "2026-02-23",
"next_holiday_name": "Emperor's Birthday"
}Endpoint
Quality
Full OpenAPI 3.1 schema is available with clear response models. The x402 challenge is live and includes a sample response. Documentation is auto-generated Swagger; no dedicated prose docs or usage examples beyond the SDK one-liner. Pricing is clear at $0.01 USDC on Base.
Warnings
- —Root URL returns 404 — no landing page, only the /docs Swagger UI is available
- —No dedicated documentation beyond auto-generated OpenAPI spec
- —The description field in the response schema is inferred from the sample; exact wording may vary
Citations
- —The API is described as the only programmatic source for Japanese FX gotobi (五十日) dates with holiday shifts through 2099https://gotobi.hugen.tokyo/docs
- —The endpoint costs $0.01 USDC on Base per call via x402https://gotobi.hugen.tokyo/gotobi/holidays/next
- —Sample response includes Emperor's Birthday on 2026-02-23https://gotobi.hugen.tokyo/gotobi/holidays/next
- —Alternative access via MCP gateway, API key, or x402-pay Python SDKhttps://gotobi.hugen.tokyo/gotobi/holidays/next