日時・カレンダーAPI

Calendar

複数国の祝日判定・営業日計算に加え、タイムゾーン間の日時変換とスケジュール計算（DST自動考慮）を提供します。

MCPツール名: get_holidays / get_calendar_month / is_holiday / add_business_days / calc_schedule

GET /v1/calendar/holidays

指定した国・年の祝日一覧を取得します。

パラメータ:

パラメータ	型	必須	説明
country	string	✓	国コード（JP / US）
year	integer	-	対象年（省略時は当年）

リクエスト例:

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

レスポンス例:

{
  "country": "JP",
  "year": 2026,
  "count": 16,
  "holidays": [
    { "date": "2026-01-01", "name": "元日" },
    { "date": "2026-01-12", "name": "成人の日" }
  ]
}

GET /v1/calendar/month

指定した年月の全日程を曜日・祝日情報付きで返します。

パラメータ:

パラメータ	型	必須	説明
year	integer	✓	年
month	integer	✓	月（1-12）
country	string	-	JP / US（デフォルト: JP）

リクエスト例:

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

レスポンス例:

{
  "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

指定した日付が祝日かどうかを判定します。

パラメータ:

パラメータ	型	必須	説明
country	string	✓	国コード（JP / US）
date	string	✓	判定する日付（YYYY-MM-DD）

リクエスト例:

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

レスポンス例:

{
  "date": "2026-01-01",
  "country": "JP",
  "is_holiday": true,
  "name": "元日"
}

GET /v1/calendar/business-days

指定した日付からN営業日後（または前）の日付を計算します。

パラメータ:

パラメータ	型	必須	説明
country	string	✓	国コード（JP / US）
from	string	✓	起算日（YYYY-MM-DD）
days	integer	✓	追加する営業日数（負の値で過去方向）

リクエスト例:

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"

レスポンス例:

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

GET /v1/calendar/schedule-calc

タイムゾーン間の日時変換とスケジュール計算を行います。サマータイム（DST）を自動考慮し、営業日・曜日指定にも対応します。

パラメータ:

パラメータ	型	必須	説明
base_time	string	✓	基点日時（ISO 8601。Z/オフセット付き、または from_timezone のローカル時刻）
from_timezone	string	✓	基点タイムゾーン（IANA。例: Asia/Tokyo）
to_timezone	string	✓	変換先タイムゾーン（IANA。例: America/New_York）
operation	string	✓	add_hours / next_business_day / next_weekday
value	string	-	時間数・営業日数・曜日名（Thursday 等）
country	string	-	next_business_day 時の祝日基準国（JP / US）
at_time	string	-	next_weekday 時の時刻（HH:MM、from_timezone 基準）

リクエスト例:

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"

レスポンス例:

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

現在時刻取得

指定タイムゾーンの現在日時をISO 8601・Unixタイムスタンプ・曜日付きで返します。外部依存なし・is_holidayやadd_business_daysと組み合わせることでエージェントが現在時刻を起点に確実に計算できます。

MCPツール名: get_current_datetime

GET /v1/datetime/now

パラメータ:

パラメータ	型	必須	説明
timezone	string	-	IANAタイムゾーン（デフォルト: UTC）
format	string	-	iso / unix / all（デフォルト: all）

リクエスト例:

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

レスポンス例:

{
  "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

Cron式を解析し、次回（および指定回数分の）実行日時を返します。タイムゾーン指定でローカル時刻基準の解釈が可能です。

MCPツール名: get_cron_next

GET /v1/cron/next

パラメータ:

パラメータ	型	必須	説明
expression	string	✓	Cron式（例: 0 9 * * 1-5）
from	string	-	基準日時（ISO 8601）。省略時は現在時刻
count	integer	-	次のN回分を返す（1〜10、デフォルト1）
timezone	string	-	IANAタイムゾーン（例: Asia/Tokyo）。省略時は UTC

リクエスト例:

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"

レスポンス例:

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

日時差分計算

2つの日時の差分を年・月・週・日・時間・分・秒の各単位で返します。外部ライブラリ不要・タイムゾーン対応。

MCPツール名: calc_datetime_diff

GET /v1/datetime/diff

パラメータ:

パラメータ	型	必須	説明
from	string	✓	開始日時（ISO8601）
to	string	✓	終了日時（ISO8601）
timezone	string	-	タイムゾーン（デフォルト: UTC）

リクエスト例:

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"

レスポンス例:

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