How to use the API

Gengō-kun exposes a free JSON API for converting between Western and Japanese calendars and looking up Japanese public holidays.

public

No authentication required. Commercial use is permitted.

data_object

Flat response structure with self-explanatory field names.

lock_open

Call directly from the browser (Access-Control-Allow-Origin: *).

Base URL

All endpoints are rooted at https://seireki.teraren.com. HTTPS only.

BASE https://seireki.teraren.com

GET /seireki/2024.json Convert a Western year to a Japanese era

Example request

curl -sH "Accept: application/json" \
  https://seireki.teraren.com/seireki/2024.json

Example response

{"seireki":"2024年","wareki":"令和6年","eto":"辰","age":2,"url":"https://seireki.teraren.com/seireki/2024.json"}

GET /wareki/2024.json Look up details for a Japanese era year

Example request

curl -sH "Accept: application/json" \
  https://seireki.teraren.com/wareki/2024.json

Example response

{"seireki":"2024年","wareki":"令和6年","eto":"辰","age":2,"url":"https://seireki.teraren.com/seireki/2024.json"}

GET /holiday/2024.json List public holidays for a year (JSON)

Example request

curl -sH "Accept: application/json" \
  https://seireki.teraren.com/holiday/2024.json

Example response

[{"date":"2024-01-01","name":"元日"},{"date":"2024-01-08","name":"成人の日"}, ...]

GET /holiday/2024.ics List public holidays for a year (iCalendar)

Example request

curl -sH "Accept: application/json" \
  https://seireki.teraren.com/holiday/2024.ics

Example response

BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:icalendar-ruby\n... (iCalendar feed)

Western and Japanese calendar endpoints return JSON. Holiday endpoints return JSON or iCalendar (.ics). Append `.json` or `.ics` to the path.

Calendar conversion supports years 1–3000 (Japanese era only where defined). Holiday lookups cover 1970 onward.