Date & Calendar APIs | Thousand API

Calendar

Holiday and business-day calculations plus cross-timezone scheduling with automatic DST handling.

MCP tools: datetime.get_holidays / datetime.get_calendar_month / datetime.is_holiday / datetime.add_business_days / datetime.add_calendar_days / datetime.generate_test_dates / datetime.check_business_hours / datetime.calc_schedule

GET /v1/calendar/holidays

Returns holidays for a given country and year.

Parameters:

Parameter	Type	Required	Description
country	string	✓	Country code (JP / US)
year	integer	-	Target year (defaults to current year)

Request example:

curl "https://api.thousand-api.com/v1/calendar/holidays?country=JP&year=2026" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "country": "JP",
  "year": 2026,
  "count": 16,
  "holidays": [
    { "date": "2026-01-01", "name": "元日" },
    { "date": "2026-01-12", "name": "成人の日" }
  ],
  "cache_ttl": 86400,
  "cached_at": "2026-06-27T12:00:00.000Z"
}

GET /v1/calendar/month

Returns every day in the given year and month with weekday and holiday metadata.

Parameters:

Parameter	Type	Required	Description
year	integer	✓	Year
month	integer	✓	Month (1-12)
country	string	-	JP / US (default: JP)

Request example:

curl "https://api.thousand-api.com/v1/calendar/month?year=2026&month=5&country=JP" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "year": 2026,
  "month": 5,
  "country": "JP",
  "days": [
    {
      "date": "2026-05-03",
      "day_of_week": "Sunday",
      "day_of_week_ja": "日",
      "is_weekend": true,
      "datetime.is_holiday": true,
      "holiday_name": "憲法記念日"
    }
  ],
  "summary": {
    "total_days": 31,
    "weekdays": 20,
    "weekends": 11,
    "holidays": 4,
    "business_days": 18
  }
}

GET /v1/calendar/is-holiday

Checks whether a given date is a holiday.

Parameters:

Parameter	Type	Required	Description
country	string	✓	Country code (JP / US)
date	string	✓	Date to check (YYYY-MM-DD)

Request example:

curl "https://api.thousand-api.com/v1/calendar/is-holiday?country=JP&date=2026-01-01" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "date": "2026-01-01",
  "country": "JP",
  "datetime.is_holiday": true,
  "name": "元日",
  "cache_ttl": 86400,
  "cached_at": "2026-06-27T12:00:00.000Z"
}

POST /v1/calendar/check-custom-holidays

Checks multiple dates against public holidays, custom non-working days (summer closure, year-end break, etc.), and optionally weekends. Returns each date's holiday status, reason (legal / custom / weekend), name, plus holiday and business-day counts.

MCP tool name: datetime.check_custom_holidays

Parameters:

Parameter	Type	Required	Description
dates	string[]	✓	Dates to check (YYYY-MM-DD, max 100 items)
country	string	-	Country code for public holidays (JP / US, default: JP)
custom_holidays	object[]	-	Custom non-working days (max 100). Each item: { date: "YYYY-MM-DD", name: "label" }
custom_holidays[].date	string	-	Non-working date (YYYY-MM-DD)
custom_holidays[].name	string	-	Label (e.g. Summer closure)
include_weekends	boolean	-	Treat Saturdays and Sundays as holidays (default: false)

Response fields:

Parameter	Type	Description
results	array	Per-date check results
results[].date	string	Date checked (YYYY-MM-DD)
results[].datetime.is_holiday	boolean	true when treated as a non-working day
results[].reason	string \| null	Reason when datetime.is_holiday is true: legal / custom / weekend; null otherwise
results[].name	string \| null	Holiday or closure name; null when datetime.is_holiday is false
holiday_count	number	Number of dates marked as holidays
business_day_count	number	Number of dates marked as business days

Priority: legal > custom > weekend. When a date is both a public holiday and a custom closure, reason is legal.

Example 1: Summer closure mixed with a public holiday (Mountain Day)

curl -X POST "https://api.thousandpokeapi.com/v1/calendar/check-custom-holidays" \
  -H "x-thousandpokeapi-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": ["2025-08-11", "2025-08-13", "2025-08-14", "2025-08-15"],
    "country": "JP",
    "custom_holidays": [
      { "date": "2025-08-13", "name": "Summer closure" },
      { "date": "2025-08-14", "name": "Summer closure" }
    ]
  }'

{
  "results": [
    { "date": "2025-08-11", "datetime.is_holiday": true, "reason": "legal", "name": "山の日" },
    { "date": "2025-08-13", "datetime.is_holiday": true, "reason": "custom", "name": "Summer closure" },
    { "date": "2025-08-14", "datetime.is_holiday": true, "reason": "custom", "name": "Summer closure" },
    { "date": "2025-08-15", "datetime.is_holiday": false, "reason": null, "name": null }
  ],
  "holiday_count": 3,
  "business_day_count": 1
}

Example 2: include_weekends: true (weekends as holidays)

curl -X POST "https://api.thousandpokeapi.com/v1/calendar/check-custom-holidays" \
  -H "x-thousandpokeapi-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": ["2025-08-15", "2025-08-16", "2025-08-17"],
    "include_weekends": true
  }'

{
  "results": [
    { "date": "2025-08-15", "datetime.is_holiday": false, "reason": null, "name": null },
    { "date": "2025-08-16", "datetime.is_holiday": true, "reason": "weekend", "name": "土曜日" },
    { "date": "2025-08-17", "datetime.is_holiday": true, "reason": "weekend", "name": "日曜日" }
  ],
  "holiday_count": 2,
  "business_day_count": 1
}

Combining with datetime.check_business_hours

Pair date-level checks (datetime.check_custom_holidays) with time-of-day checks (datetime.check_business_hours) for full business calendar coverage: filter non-working dates first, then verify opening hours.

curl -X POST "https://api.thousandpokeapi.com/v1/batch/execute" \
  -H "x-thousandpokeapi-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {
        "id": "holidays",
        "method": "POST",
        "path": "/v1/calendar/check-custom-holidays",
        "body": {
          "dates": ["2025-08-15"],
          "country": "JP",
          "custom_holidays": [{ "date": "2025-08-14", "name": "Summer closure" }]
        }
      },
      {
        "id": "hours",
        "method": "POST",
        "path": "/v1/calendar/business-hours",
        "body": {
          "datetime": "2025-08-15T10:00:00+09:00",
          "timezone": "Asia/Tokyo",
          "country": "JP",
          "hours": {
            "mon": { "open": "09:00", "close": "18:00" },
            "tue": { "open": "09:00", "close": "18:00" },
            "wed": { "open": "09:00", "close": "18:00" },
            "thu": { "open": "09:00", "close": "18:00" },
            "fri": { "open": "09:00", "close": "18:00" },
            "sat": null,
            "sun": null
          }
        }
      }
    ]
  }'

GET /v1/calendar/business-days

Calculates the date N business days after (or before) a start date.

Parameters:

Parameter	Type	Required	Description
country	string	✓	Country code (JP / US)
from	string	✓	Start date (YYYY-MM-DD)
days	integer	✓	Business days to add (negative for past)

Request example:

curl "https://api.thousand-api.com/v1/calendar/business-days?country=JP&from=2026-01-01&days=5" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "from": "2026-01-01",
  "days": 5,
  "country": "JP",
  "result": "2026-01-08"
}

GET /v1/calendar/add-days

Add or subtract calendar days from a date. Weekends and holidays are counted as regular days. Useful for expiry dates, deadlines, and seeding test data.

MCP tool name: datetime.add_calendar_days

Parameters:

Parameter	Type	Required	Description
date	string	✓	Base date (YYYY-MM-DD)
days	integer	✓	Days to add (negative to subtract, 0 allowed)
timezone	string	-	IANA timezone (default: Asia/Tokyo)

Response fields:

Parameter	Type	Description
input_date	string	Input date (YYYY-MM-DD)
days	integer	Days added (negative for subtraction)
timezone	string	Timezone used for calculation
result_date	string	Result date (YYYY-MM-DD)
sql_hint	string	MySQL/PostgreSQL SQL expression (DATE_ADD / DATE_SUB)

Example 1: Add 5 days (2025-03-28 + 5 → 2025-04-02)

curl "https://api.thousand-api.com/v1/calendar/add-days?date=2025-03-28&days=5" \
  -H "x-api-key: YOUR_API_KEY"

{
  "input_date": "2025-03-28",
  "days": 5,
  "timezone": "Asia/Tokyo",
  "result_date": "2025-04-02",
  "sql_hint": "DATE_ADD('2025-03-28', INTERVAL 5 DAY)"
}

Example 2: Subtract 7 days (days: -7)

curl "https://api.thousand-api.com/v1/calendar/add-days?date=2025-01-01&days=-7" \
  -H "x-api-key: YOUR_API_KEY"

{
  "input_date": "2025-01-01",
  "days": -7,
  "timezone": "Asia/Tokyo",
  "result_date": "2024-12-25",
  "sql_hint": "DATE_SUB('2025-01-01', INTERVAL 7 DAY)"
}

Using sql_hint with Laravel Eloquent

// Use the sql_hint from the API response in a DB query
$response = Http::withHeaders(['x-api-key' => $key])
    ->get('https://api.thousand-api.com/v1/calendar/add-days', [
        'date' => '2025-03-28',
        'days' => 30,
    ])->json();

// Apply calendar-day SQL to an expiry column
$expiryDate = DB::table('subscriptions')
    ->selectRaw("{$response['sql_hint']} AS expiry_date")
    ->where('id', $id)
    ->value('expiry_date');

// Or use as a raw expression in Eloquent
Subscription::where('id', $id)
    ->update(['expires_at' => DB::raw($response['sql_hint'])]);

POST /v1/datetime/generate-test-dates

Generate a batch of test dates from a base date and day-offset array. Returns human-readable labels and a SQL INSERT VALUES hint. Useful for expiry/availability boundary dates (-30, -7, 0, +7, +30 days).

MCP tool name: datetime.generate_test_dates

Parameters:

Parameter	Type	Required	Description
base_date	string	✓	Base date (YYYY-MM-DD) or "today"
offsets	number[]	✓	Day offset array (max 100 items, integers only)
timezone	string	-	IANA timezone (default: Asia/Tokyo)
format	string	-	Output format: iso (YYYY-MM-DD) / sql ('YYYY-MM-DD') / unix (seconds as string)

Response fields:

Parameter	Type	Description
base_date	string	Resolved base date used (YYYY-MM-DD)
timezone	string	Timezone used
format	string	Output format used (iso / sql / unix)
results	array	Per-offset results (offset, date, label)
results[].offset	integer	Input offset value
results[].date	string	Date per format (iso: YYYY-MM-DD, sql: 'YYYY-MM-DD', unix: second timestamp)
results[].label	string	Human label (e.g. 30 days ago, today, 7 days later)
sql_insert_hint	string	SQL INSERT VALUES hint comment

Example 1: Batch boundary dates (offsets: [-30, -7, 0, 7, 30])

curl -X POST "https://api.thousand-api.com/v1/datetime/generate-test-dates" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"base_date":"2025-06-15","offsets":[-30,-7,0,7,30]}'

{
  "base_date": "2025-06-15",
  "timezone": "Asia/Tokyo",
  "format": "iso",
  "results": [
    { "offset": -30, "date": "2025-05-16", "label": "30日前" },
    { "offset": -7,  "date": "2025-06-08", "label": "7日前" },
    { "offset": 0,   "date": "2025-06-15", "label": "当日" },
    { "offset": 7,   "date": "2025-06-22", "label": "7日後" },
    { "offset": 30,  "date": "2025-07-15", "label": "30日後" }
  ],
  "sql_insert_hint": "-- INSERT VALUES ('2025-05-16', '2025-06-08', '2025-06-15', '2025-06-22', '2025-07-15')"
}

Example 2: format: sql + Laravel Seeder

curl -X POST "https://api.thousand-api.com/v1/datetime/generate-test-dates" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"base_date":"2025-06-15","offsets":[-7,0,7],"format":"sql"}'

{
  "base_date": "2025-06-15",
  "timezone": "Asia/Tokyo",
  "format": "sql",
  "results": [
    { "offset": -7, "date": "'2025-06-08'", "label": "7日前" },
    { "offset": 0,  "date": "'2025-06-15'", "label": "当日" },
    { "offset": 7,  "date": "'2025-06-22'", "label": "7日後" }
  ],
  "sql_insert_hint": "-- INSERT VALUES ('2025-06-08', '2025-06-15', '2025-06-22')"
}

Using sql_insert_hint in a Laravel Seeder

<?php
// Seeder example
$response = Http::withHeaders(['x-api-key' => $key])
    ->post('https://api.thousand-api.com/v1/datetime/generate-test-dates', [
        'base_date' => '2025-06-15',
        'offsets'   => [-7, 0, 7],
        'format'    => 'sql',
    ])->json();

$values = collect($response['results'])->pluck('date')->implode(', ');
// Pass sql_insert_hint values into DB::statement()
DB::statement("INSERT INTO test_orders (order_date) VALUES {$values}");

POST /v1/calendar/business-hours

Checks whether a given datetime falls within business hours. Considers timezone, per-day schedules, and optional public holidays (when country is set). Returns the closed reason and next opening time.

MCP tool name: datetime.check_business_hours

Parameters:

Parameter	Type	Required	Description
datetime	string	✓	Datetime to check (ISO 8601, e.g. 2025-12-25T10:00:00+09:00)
timezone	string	-	IANA timezone (default: Asia/Tokyo)
hours	object	✓	Business hours per weekday (mon–sun). Value is { open, close } (HH:MM) or null (closed)
hours.mon–sun.open	string	-	Opening time (HH:MM)
hours.mon–sun.close	string	-	Closing time (HH:MM)
country	string	-	Country code for holidays (JP / US). Omit to ignore holidays

Response fields:

Parameter	Type	Description
datetime	string	Echo of the request datetime
timezone	string	Timezone used for evaluation
is_open	boolean	true when within business hours
reason	string \| null	Closed reason when is_open is false: holiday / closed_day / before_open / after_close
holiday_name	string \| null	Holiday name when reason is holiday
next_open	string \| null	Next opening datetime (ISO 8601 with offset). null if none within 7 days

reason values: holiday / closed_day / before_open / after_close

Example 1: Weekdays 9–18, closed on holidays (country: JP)

curl -X POST "https://api.thousand-api.com/v1/calendar/business-hours" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "2025-01-01T10:00:00+09:00",
    "timezone": "Asia/Tokyo",
    "country": "JP",
    "hours": {
      "mon": { "open": "09:00", "close": "18:00" },
      "tue": { "open": "09:00", "close": "18:00" },
      "wed": { "open": "09:00", "close": "18:00" },
      "thu": { "open": "09:00", "close": "18:00" },
      "fri": { "open": "09:00", "close": "18:00" },
      "sat": null,
      "sun": null
    }
  }'

{
  "datetime": "2025-01-01T10:00:00+09:00",
  "timezone": "Asia/Tokyo",
  "is_open": false,
  "reason": "holiday",
  "holiday_name": "元日",
  "next_open": "2025-01-02T09:00:00+09:00"
}

Example 2: Within business hours (is_open: true)

curl -X POST "https://api.thousand-api.com/v1/calendar/business-hours" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "2025-06-02T10:00:00+09:00",
    "timezone": "Asia/Tokyo",
    "hours": {
      "mon": { "open": "09:00", "close": "18:00" },
      "tue": { "open": "09:00", "close": "18:00" },
      "wed": { "open": "09:00", "close": "18:00" },
      "thu": { "open": "09:00", "close": "18:00" },
      "fri": { "open": "09:00", "close": "18:00" },
      "sat": null,
      "sun": null
    }
  }'

{
  "datetime": "2025-06-02T10:00:00+09:00",
  "timezone": "Asia/Tokyo",
  "is_open": true,
  "reason": null,
  "holiday_name": null,
  "next_open": null
}

Example 3: Without country (holidays ignored)

curl -X POST "https://api.thousand-api.com/v1/calendar/business-hours" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "2025-01-01T10:00:00+09:00",
    "timezone": "Asia/Tokyo",
    "hours": {
      "mon": { "open": "09:00", "close": "18:00" },
      "tue": { "open": "09:00", "close": "18:00" },
      "wed": { "open": "09:00", "close": "18:00" },
      "thu": { "open": "09:00", "close": "18:00" },
      "fri": { "open": "09:00", "close": "18:00" },
      "sat": null,
      "sun": null
    }
  }'

{
  "datetime": "2025-01-01T10:00:00+09:00",
  "timezone": "Asia/Tokyo",
  "is_open": true,
  "reason": null,
  "holiday_name": null,
  "next_open": null
}

datetime.get_current_datetime + datetime.check_business_hours (data.execute_batch)

curl -X POST "https://api.thousand-api.com/v1/batch/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {
        "id": "now",
        "method": "GET",
        "path": "/v1/datetime/now",
        "query": { "timezone": "Asia/Tokyo" }
      },
      {
        "id": "open",
        "method": "POST",
        "path": "/v1/calendar/business-hours",
        "body": {
          "datetime": "{{now.iso}}",
          "timezone": "Asia/Tokyo",
          "country": "JP",
          "hours": {
            "mon": { "open": "09:00", "close": "18:00" },
            "tue": { "open": "09:00", "close": "18:00" },
            "wed": { "open": "09:00", "close": "18:00" },
            "thu": { "open": "09:00", "close": "18:00" },
            "fri": { "open": "09:00", "close": "18:00" },
            "sat": null,
            "sun": null
          }
        }
      }
    ]
  }'

GET /v1/calendar/schedule-calc

Converts datetimes across timezones and computes schedules. Handles DST automatically; supports business-day and weekday operations.

Parameters:

Parameter	Type	Required	Description
base_time	string	✓	Base datetime (ISO 8601 with Z/offset, or local time in from_timezone)
from_timezone	string	✓	Source IANA timezone (e.g. Asia/Tokyo)
to_timezone	string	✓	Destination IANA timezone (e.g. America/New_York)
operation	string	✓	add_hours / next_business_day / next_weekday
value	string	-	Hours, business days, or weekday name (e.g. Thursday)
country	string	-	Holiday country for next_business_day (JP / US)
at_time	string	-	Clock time HH:MM in from_timezone for next_weekday

Request example:

curl "https://api.thousand-api.com/v1/calendar/schedule-calc?base_time=2026-05-21T09:00:00&from_timezone=America/New_York&to_timezone=Asia/Tokyo&operation=next_business_day&value=1&country=US" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "input": {
    "base_time": "2026-05-21T09:00:00-04:00",
    "from_timezone": "America/New_York",
    "to_timezone": "Asia/Tokyo",
    "operation": "next_business_day",
    "value": "1",
    "country": "US"
  },
  "result": {
    "target_time_source_tz": "2026-05-22T09:00:00-04:00",
    "target_time_dest_tz": "2026-05-22T22:00:00+09:00",
    "is_dst": false,
    "formatted": "Friday, May 22, 2026 at 10:00 PM GMT+9"
  }
}

Current Datetime

Returns the current datetime for a timezone as ISO 8601, Unix timestamp, and weekday fields. No external dependencies. Combine with datetime.is_holiday or datetime.add_business_days so agents anchor calculations on real time.

MCP tool: datetime.get_current_datetime

GET /v1/datetime/now

Parameters:

Parameter	Type	Required	Description
timezone	string	-	IANA timezone (default: Asia/Tokyo)
format	string	-	iso / unix / all (default: all)

Request example:

curl "https://api.thousand-api.com/v1/datetime/now?timezone=Asia%2FTokyo" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "timezone": "Asia/Tokyo",
  "iso": "2026-06-01T09:30:00+09:00",
  "unix": 1748739000,
  "utc_iso": "2026-06-01T00:30:00Z",
  "date": "2026-06-01",
  "time": "09:30:00",
  "weekday": "Sunday",
  "weekday_ja": "日曜日",
  "is_weekend": true
}

Cron

Parses a cron expression and returns the next N execution times (ISO 8601 UTC). Optional timezone interprets the schedule in local time.

MCP tool: datetime.get_cron_next

GET /v1/cron/next

Parameters:

Parameter	Type	Required	Description
expression	string	✓	Cron expression (e.g. 0 9 * * 1-5)
from	string	-	Base datetime (ISO 8601). Defaults to now
count	integer	-	Number of next runs to return (1–10, default 1)
timezone	string	-	IANA timezone (e.g. Asia/Tokyo). Defaults to Asia/Tokyo

Request example:

curl "https://api.thousand-api.com/v1/cron/next?expression=0%209%20*%20*%201-5&timezone=Asia/Tokyo&count=2" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "expression": "0 9 * * 1-5",
  "timezone": "Asia/Tokyo",
  "description": "At 09:00 AM, Monday through Friday",
  "next": [
    "2026-05-22T00:00:00.000Z",
    "2026-05-25T00:00:00.000Z"
  ]
}

POST /v1/cron/laravel

Converts Laravel scheduler expressions (`dailyAt()`, `weeklyOn()`, `between()`, etc.) to cron and returns the next execution times. Verify `app/Console/Kernel.php` schedules without running the app.

MCP tool: datetime.parse_laravel_schedule

Parameters:

Parameter	Type	Required	Description
expression	string	✓	Laravel schedule expression (e.g. dailyAt('03:30'))
base_datetime	string	-	Base datetime (ISO 8601). Defaults to now
timezone	string	-	IANA timezone (default: Asia/Tokyo)
count	integer	-	Number of next runs (1–10, default 3)

Response fields

Parameter	Type	Description
expression	string	Input Laravel expression
cron_equivalent	string	Converted 5-field cron expression
timezone	string	Timezone used
between_start	string	Start time when between() is used (HH:MM)
between_end	string	End time when between() is used (HH:MM)
next_runs	string[]	Next run times (ISO 8601 with offset)

Supported methods (Laravel → cron)

Parameter	Type	Description
everyMinute()	* * * * *	Every minute
everyFiveMinutes()	/5 * * *	Every 5 minutes
hourly()	0 * * * *	Every hour at :00
hourlyAt(17)	17 * * * *	Every hour at :17
daily()	0 0 * * *	Daily at midnight
dailyAt('13:00')	0 13 * * *	Daily at 13:00
twiceDaily(1, 13)	0 1,13 * * *	Daily at 1:00 and 13:00
weekly()	0 0 * * 0	Weekly on Sunday at midnight
weeklyOn(1, '8:00')	0 8 * * 1	Weekly on Monday at 8:00
monthly()	0 0 1 * *	Monthly on the 1st
monthlyOn(4, '15:00')	0 15 4 * *	Monthly on the 4th at 15:00
quarterly()	0 0 1 1,4,7,10 *	Quarterly
yearly()	0 0 1 1 *	Yearly on Jan 1
cron('* * * * *')	(as-is)	Arbitrary cron expression

Basic: dailyAt('03:30')

curl -X POST "https://api.thousand-api.com/v1/cron/laravel" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "dailyAt('\''03:30'\'')",
    "base_datetime": "2025-06-15T00:00:00+09:00",
    "count": 3
  }'

{
  "expression": "dailyAt('03:30')",
  "cron_equivalent": "30 3 * * *",
  "timezone": "Asia/Tokyo",
  "next_runs": [
    "2025-06-15T03:30:00+09:00",
    "2025-06-16T03:30:00+09:00",
    "2025-06-17T03:30:00+09:00"
  ]
}

With between(): hourly()->between('9:00', '17:00')

curl -X POST "https://api.thousand-api.com/v1/cron/laravel" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "hourly()->between('\''9:00'\'', '\''17:00'\'')",
    "base_datetime": "2025-06-15T08:00:00+09:00",
    "count": 5
  }'

{
  "expression": "hourly()->between('9:00', '17:00')",
  "cron_equivalent": "0 * * * *",
  "timezone": "Asia/Tokyo",
  "between_start": "09:00",
  "between_end": "17:00",
  "next_runs": [
    "2025-06-15T09:00:00+09:00",
    "2025-06-15T10:00:00+09:00",
    "2025-06-15T11:00:00+09:00",
    "2025-06-15T12:00:00+09:00",
    "2025-06-15T13:00:00+09:00"
  ]
}

Advanced: pass cron_equivalent to datetime.get_cron_next

curl "https://api.thousand-api.com/v1/cron/next?expression=30%203%20*%20*%20*&timezone=Asia%2FTokyo&count=3" \
  -H "x-api-key: YOUR_API_KEY"

Datetime Difference

Returns the difference between two datetimes in years, months, weeks, days, hours, minutes, and seconds. No external dependencies; timezone parameter supported.

MCP tool: datetime.calc_datetime_diff

GET /v1/datetime/diff

Parameters:

Parameter	Type	Required	Description
from	string	✓	Start datetime (ISO 8601)
to	string	✓	End datetime (ISO 8601)
timezone	string	-	IANA timezone (default: Asia/Tokyo)

Request example:

curl "https://api.thousand-api.com/v1/datetime/diff?from=2026-01-01T00%3A00%3A00Z&to=2026-12-31T23%3A59%3A59Z" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "from": "2026-01-01T00:00:00Z",
  "to": "2026-12-31T23:59:59Z",
  "timezone": "Asia/Tokyo",
  "is_negative": false,
  "diff": {
    "years": 0,
    "months": 11,
    "weeks": 52,
    "days": 364,
    "hours": 8759,
    "minutes": 525599,
    "seconds": 31535999
  },
  "human_readable": "11 months, 30 days"
}

Format Relative Time

Converts an absolute ISO 8601 datetime into locale-aware relative phrases such as "3 hours ago" or "yesterday". Ideal for logs, notifications, and chat UIs.

MCP tool: datetime.format_relative_time

GET /v1/datetime/relative

Parameters:

Parameter	Type	Required	Description
datetime	string	✓	Target datetime (ISO 8601)
reference	string	-	Reference datetime (defaults to server current time)
locale	string	-	BCP 47 locale (default: ja-JP)
style	string	-	long / short / narrow (default: long)
timezone	string	-	IANA timezone (default: Asia/Tokyo)

Request example:

curl "https://api.thousand-api.com/v1/datetime/relative?datetime=2026-06-13T06%3A00%3A00Z&reference=2026-06-13T09%3A00%3A00Z&locale=ja-JP&style=long&timezone=Asia%2FTokyo" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "datetime": "2026-06-13T06:00:00Z",
  "reference": "2026-06-13T09:00:00Z",
  "locale": "ja-JP",
  "style": "long",
  "timezone": "Asia/Tokyo",
  "relative": "3時間前",
  "relative_en": "3 hours ago",
  "diff_seconds": -10800,
  "diff_human": { "hours": -3, "minutes": 0, "seconds": 0 }
}

Convert Japanese Era

Converts between Japanese era (元号) years and Gregorian calendar dates. Supports Meiji, Taisho, Showa, Heisei, and Reiwa with accurate handling of era boundary dates (e.g. 2019-04-30 Heisei 31 / 2019-05-01 Reiwa 1).

MCP tool: datetime.convert_japanese_era

GET /v1/datetime/era/convert

Parameters (direction=to_gregorian):

Parameter	Type	Required	Description
direction	string	✓	to_gregorian
era	string	✓	Era name (reiwa / heisei / showa / taisho / meiji or Japanese labels)
era_year	integer	✓	Era year (1-based; year 1 = 元年)
month	integer	-	Month (1-12, default: 1)
day	integer	-	Day (1-31, default: 1)

Parameters (direction=to_japanese_era):

Parameter	Type	Required	Description
direction	string	✓	to_japanese_era
date	string	✓	Gregorian date (YYYY-MM-DD)

Response fields (direction=to_gregorian):

Parameter	Type	Description
direction	string	to_gregorian
input	object	Request input (era, era_year, month?, day?)
output.date	string	Gregorian date (YYYY-MM-DD)
output.year	integer	Gregorian year
output.month	integer	Month
output.day	integer	Day
era_label_ja	string	Japanese era label (e.g. 令和)
era_label_en	string	English era label (e.g. Reiwa)

Response fields (direction=to_japanese_era):

Parameter	Type	Description
direction	string	to_japanese_era
input	object	Request input (date)
output.era	string	Era code (reiwa / heisei / etc.)
output.era_year	integer	Era year (1-based)
output.year_label	string	Era year label (e.g. 令和7年 / 令和元年)
output.month	integer	Month
output.day	integer	Day
era_label_ja	string	Japanese era label
era_label_en	string	English era label

Supported eras:

Parameter	Type	Description
Meiji (meiji)	1868-01-25	1912-07-29
Taisho (taisho)	1912-07-30	1926-12-24
Showa (showa)	1926-12-25	1989-01-07
Heisei (heisei)	1989-01-08	2019-04-30
Reiwa (reiwa)	2019-05-01	ongoing

Example 1: Japanese era → Gregorian (Reiwa 7, May 1)

curl "https://api.thousand-api.com/v1/datetime/era/convert?direction=to_gregorian&era=reiwa&era_year=7&month=5&day=1" \
  -H "x-api-key: YOUR_API_KEY"

{
  "direction": "to_gregorian",
  "input": {
    "era": "reiwa",
    "era_year": 7,
    "month": 5,
    "day": 1
  },
  "output": {
    "date": "2025-05-01",
    "year": 2025,
    "month": 5,
    "day": 1
  },
  "era_label_ja": "令和",
  "era_label_en": "Reiwa"
}

Example 2: Gregorian → Japanese era (2019-04-30 = Heisei 31, last day of Heisei)

curl "https://api.thousand-api.com/v1/datetime/era/convert?direction=to_japanese_era&date=2019-04-30" \
  -H "x-api-key: YOUR_API_KEY"

{
  "direction": "to_japanese_era",
  "input": {
    "date": "2019-04-30"
  },
  "output": {
    "era": "heisei",
    "era_year": 31,
    "year_label": "平成31年",
    "month": 4,
    "day": 30
  },
  "era_label_ja": "平成",
  "era_label_en": "Heisei"
}

Example 3: Gregorian → Japanese era (2019-05-01 = Reiwa gannen, first day of Reiwa)

curl "https://api.thousand-api.com/v1/datetime/era/convert?direction=to_japanese_era&date=2019-05-01" \
  -H "x-api-key: YOUR_API_KEY"

{
  "direction": "to_japanese_era",
  "input": {
    "date": "2019-05-01"
  },
  "output": {
    "era": "reiwa",
    "era_year": 1,
    "year_label": "令和元年",
    "month": 5,
    "day": 1
  },
  "era_label_ja": "令和",
  "era_label_en": "Reiwa"
}

Convert ISO Duration

Parse ISO 8601 duration strings (e.g. PT1H30M, P1DT2H) into components (days, hours, minutes, seconds) and total seconds, or format components into ISO 8601 strings. Prevents confusion between PT1H, 3600 seconds, and "1 hour" in S3 presigned URL expiry, JWT exp calculation, and timeout settings.

MCP tool name: datetime.convert_iso_duration

POST /v1/datetime/duration/convert

Parameters (direction=parse):

Parameter	Type	Required	Description
direction	string	✓	parse
duration	string	✓	ISO 8601 duration string (e.g. PT1H30M45S)
include_months_years	boolean	-	Allow approximate conversion when years/months are present (default: false)

Parameters (direction=format):

Parameter	Type	Required	Description
direction	string	✓	format
days	number	-	Days (≥ 0)
hours	number	-	Hours (≥ 0)
minutes	number	-	Minutes (≥ 0)
seconds	number	-	Seconds (≥ 0, decimals allowed, max 3 decimal places)
years	number	-	Years (when include_months_years=true)
months	number	-	Months (when include_months_years=true)
include_months_years	boolean	-	Set true when including year/month components (default: false)

Response fields (direction=parse):

Parameter	Type	Description
direction	string	parse
input	string	Input duration string
output.days	number	Days
output.hours	number	Hours
output.minutes	number	Minutes
output.seconds	number	Seconds
output.total_seconds	number	Total seconds (years/months approximated when included)
output.years	number	Years (when present)
output.months	number	Months (when present)
iso_duration	string	Normalized ISO 8601 string
warnings	string[]	Warnings when years/months are included (optional)

Response fields (direction=format):

Parameter	Type	Description
direction	string	format
input	object	Request input (components)
output	string	Generated ISO 8601 duration string
total_seconds	number	Total seconds
warnings	string[]	Warnings when years/months are included (optional)

Example 1: parse — decompose PT1H30M45S into components and seconds

curl -X POST "https://api.thousand-api.com/v1/datetime/duration/convert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "parse",
    "duration": "PT1H30M45S"
  }'

{
  "direction": "parse",
  "input": "PT1H30M45S",
  "output": {
    "days": 0,
    "hours": 1,
    "minutes": 30,
    "seconds": 45,
    "total_seconds": 5445
  },
  "iso_duration": "PT1H30M45S"
}

Example 2: format — days=1, hours=2 → P1DT2H

curl -X POST "https://api.thousand-api.com/v1/datetime/duration/convert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "format",
    "days": 1,
    "hours": 2
  }'

{
  "direction": "format",
  "input": {
    "days": 1,
    "hours": 2
  },
  "output": "P1DT2H",
  "total_seconds": 93600
}

Example 3: include_months_years=true — accept P1Y6M and return warnings

curl -X POST "https://api.thousand-api.com/v1/datetime/duration/convert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "parse",
    "duration": "P1Y6M",
    "include_months_years": true
  }'

{
  "direction": "parse",
  "input": "P1Y6M",
  "output": {
    "years": 1,
    "months": 6,
    "days": 0,
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "total_seconds": 47088000
  },
  "iso_duration": "P1Y6M",
  "warnings": [
    "years and months are calendar-dependent and converted approximately (1 year = 365 days, 1 month = 30 days). Results may vary."
  ]
}

Date & calendar