Thousand API

Date & calendar

Calendar

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

MCP tools: get_holidays / get_calendar_month / is_holiday / add_business_days / calc_schedule

GET /v1/calendar/holidays

Returns holidays for a given country and year.

Parameters:

ParameterTypeRequiredDescription
countrystring✓Country code (JP / US)
yearinteger-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": "成人の日" }
  ]
}

GET /v1/calendar/month

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

Parameters:

ParameterTypeRequiredDescription
yearinteger✓Year
monthinteger✓Month (1-12)
countrystring-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,
      "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:

ParameterTypeRequiredDescription
countrystring✓Country code (JP / US)
datestring✓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",
  "is_holiday": true,
  "name": "元日"
}

GET /v1/calendar/business-days

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

Parameters:

ParameterTypeRequiredDescription
countrystring✓Country code (JP / US)
fromstring✓Start date (YYYY-MM-DD)
daysinteger✓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/schedule-calc

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

Parameters:

ParameterTypeRequiredDescription
base_timestring✓Base datetime (ISO 8601 with Z/offset, or local time in from_timezone)
from_timezonestring✓Source IANA timezone (e.g. Asia/Tokyo)
to_timezonestring✓Destination IANA timezone (e.g. America/New_York)
operationstring✓add_hours / next_business_day / next_weekday
valuestring-Hours, business days, or weekday name (e.g. Thursday)
countrystring-Holiday country for next_business_day (JP / US)
at_timestring-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 is_holiday or add_business_days so agents anchor calculations on real time.

MCP tool: get_current_datetime

GET /v1/datetime/now

Parameters:

ParameterTypeRequiredDescription
timezonestring-IANA timezone (default: UTC)
formatstring-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: get_cron_next

GET /v1/cron/next

Parameters:

ParameterTypeRequiredDescription
expressionstring✓Cron expression (e.g. 0 9 * * 1-5)
fromstring-Base datetime (ISO 8601). Defaults to now
countinteger-Number of next runs to return (1–10, default 1)
timezonestring-IANA timezone (e.g. Asia/Tokyo). Defaults to UTC

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"
  ]
}

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: calc_datetime_diff

GET /v1/datetime/diff

Parameters:

ParameterTypeRequiredDescription
fromstring✓Start datetime (ISO 8601)
tostring✓End datetime (ISO 8601)
timezonestring-IANA timezone (default: UTC)

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": "UTC",
  "is_negative": false,
  "diff": {
    "years": 0,
    "months": 11,
    "weeks": 52,
    "days": 364,
    "hours": 8759,
    "minutes": 525599,
    "seconds": 31535999
  },
  "human_readable": "11 months, 30 days"
}