日時・カレンダーAPI

Calendar

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

MCPツール名: 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

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

パラメータ:

パラメータ	型	必須	説明
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": "成人の日" }
  ],
  "cache_ttl": 86400,
  "cached_at": "2026-06-27T12:00:00.000Z"
}

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,
      "datetime.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",
  "datetime.is_holiday": true,
  "name": "元日",
  "cache_ttl": 86400,
  "cached_at": "2026-06-27T12:00:00.000Z"
}

POST /v1/calendar/check-custom-holidays

複数の日付を法定祝日・カスタム休業日（夏季休暇・年末年始など）・任意で土日までまとめて判定します。各日付の休日フラグ・理由（legal / custom / weekend）・名称と、休日数・営業日数のサマリーを返します。

MCPツール名: datetime.check_custom_holidays

パラメータ:

パラメータ	型	必須	説明
dates	string[]	✓	判定対象日付（YYYY-MM-DD、最大100件）
country	string	-	法定祝日の国コード（JP / US、デフォルト: JP）
custom_holidays	object[]	-	カスタム休業日（最大100件）。各要素は { date: "YYYY-MM-DD", name: "名称" }
custom_holidays[].date	string	-	休業日（YYYY-MM-DD）
custom_holidays[].name	string	-	休業日名称（例: 夏季休暇）
include_weekends	boolean	-	土日も休日とみなす（デフォルト: false）

レスポンスフィールド:

パラメータ	型	説明
results	array	各日付の判定結果
results[].date	string	判定対象日付（YYYY-MM-DD）
results[].datetime.is_holiday	boolean	休日なら true
results[].reason	string \| null	休日理由。datetime.is_holiday: false のとき null。legal（法定祝日）/ custom（カスタム休業日）/ weekend（土日）
results[].name	string \| null	祝日・休業日名称。datetime.is_holiday: false のとき null
holiday_count	number	休日と判定された件数
business_day_count	number	営業日と判定された件数

reason の優先順位: legal > custom > weekend。法定祝日とカスタム休業日が重なる日は legal が返ります。

例1: 夏季休暇 + 法定祝日（山の日）の混在判定

curl -X POST "https://api.thousandpokeapi.com/v1/calendar/check-custom-holidays" \
  -H "x-api-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": "夏季休暇" },
      { "date": "2025-08-14", "name": "夏季休暇" }
    ]
  }'

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

例2: include_weekends: true（土日も休日扱い）

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
}

datetime.check_business_hours との組み合わせ

日付単位の休業判定（datetime.check_custom_holidays）と、時刻を含む営業時間判定（datetime.check_business_hours）を組み合わせると、完全な営業カレンダー管理ができます。まず休日でない日を絞り込み、営業時間 API で開店時間内かを確認します。

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": "夏季休暇" }]
        }
      },
      {
        "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

指定した日付から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/add-days

指定した日付に暦日（カレンダー日）を加算・減算します。土日・祝日は無視し、純粋な日数計算を行います。有効期限・締切日・テストデータの日付生成などに使えます。

MCPツール名: datetime.add_calendar_days

パラメータ:

パラメータ	型	必須	説明
date	string	✓	基準日（YYYY-MM-DD）
days	integer	✓	加算日数（負数で減算、0 も可）
timezone	string	-	IANA タイムゾーン（デフォルト: Asia/Tokyo）

レスポンスフィールド:

パラメータ	型	説明
input_date	string	入力日付（YYYY-MM-DD）
days	integer	加算日数（負数は減算）
timezone	string	使用したタイムゾーン
result_date	string	計算結果（YYYY-MM-DD）
sql_hint	string	MySQL/PostgreSQL 相当の SQL 式（DATE_ADD / DATE_SUB）

例1: 5日後を計算（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)"
}

例2: 7日前を計算（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)"
}

sql_hint の活用例（Laravel Eloquent）

// API レスポンスの sql_hint を DB クエリに利用
$response = Http::withHeaders(['x-api-key' => $key])
    ->get('https://api.thousand-api.com/v1/calendar/add-days', [
        'date' => '2025-03-28',
        'days' => 30,
    ])->json();

// 有効期限カラムに暦日加算 SQL を適用
$expiryDate = DB::table('subscriptions')
    ->selectRaw("{$response['sql_hint']} AS expiry_date")
    ->where('id', $id)
    ->value('expiry_date');

// または Eloquent で raw 式として使用
Subscription::where('id', $id)
    ->update(['expires_at' => DB::raw($response['sql_hint'])]);

POST /v1/datetime/generate-test-dates

基準日と日数オフセットの配列から、テスト用の日付セットを一括生成します。人間が読みやすいラベルと SQL INSERT VALUES ヒント付きで返します。有効期限・利用可能期間の境界日（-30, -7, 0, +7, +30 日など）のテストデータ生成に便利です。

MCPツール名: datetime.generate_test_dates

パラメータ:

パラメータ	型	必須	説明
base_date	string	✓	基準日（YYYY-MM-DD）または "today"
offsets	number[]	✓	日数オフセット配列（最大100件、整数のみ）
timezone	string	-	IANA タイムゾーン（デフォルト: Asia/Tokyo）
format	string	-	出力形式: iso（YYYY-MM-DD）/ sql（'YYYY-MM-DD'）/ unix（秒タイムスタンプ文字列）

レスポンスフィールド:

パラメータ	型	説明
base_date	string	実際に使用した基準日（YYYY-MM-DD）
timezone	string	使用したタイムゾーン
format	string	使用した出力形式（iso / sql / unix）
results	array	各オフセットの計算結果（offset, date, label）
results[].offset	integer	入力オフセット値
results[].date	string	format に応じた日付（iso: YYYY-MM-DD、sql: 'YYYY-MM-DD'、unix: 秒タイムスタンプ）
results[].label	string	人間向けラベル（例: 30日前、当日、7日後）
sql_insert_hint	string	SQL INSERT VALUES 句のヒントコメント

例1: 境界日セットを一括生成（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')"
}

例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')"
}

sql_insert_hint の活用例（Laravel Seeder）

<?php
// Seeder での活用例
$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(', ');
// sql_insert_hint をそのまま DB::statement() に渡す
DB::statement("INSERT INTO test_orders (order_date) VALUES {$values}");

POST /v1/calendar/business-hours

指定した日時が営業時間内かどうかを判定します。タイムゾーン・曜日ごとの営業時間・祝日（country 指定時）を考慮し、休業理由と次の営業開始日時を返します。

MCPツール名: datetime.check_business_hours

パラメータ:

パラメータ	型	必須	説明
datetime	string	✓	判定する日時（ISO 8601。例: 2025-12-25T10:00:00+09:00）
timezone	string	-	IANAタイムゾーン（デフォルト: Asia/Tokyo）
hours	object	✓	曜日ごとの営業時間。キーは mon〜sun。値は { open, close }（HH:MM）または null（定休日）
hours.mon〜sun.open	string	-	営業開始時刻（HH:MM）
hours.mon〜sun.close	string	-	営業終了時刻（HH:MM）
country	string	-	祝日判定用国コード（JP / US）。省略時は祝日を考慮しない

レスポンスフィールド:

パラメータ	型	説明
datetime	string	リクエストの datetime をそのまま返す
timezone	string	使用したタイムゾーン
is_open	boolean	営業時間内なら true
reason	string \| null	休業理由。is_open: true のとき null。holiday / closed_day / before_open / after_close
holiday_name	string \| null	reason が holiday のときの祝日名
next_open	string \| null	次の営業開始日時（ISO 8601・タイムゾーンオフセット付き）。7日以内に見つからない場合は null

reason の値: holiday（祝日）/ closed_day（定休日）/ before_open（営業開始前）/ after_close（営業終了後）

例1: 平日9〜18時営業・祝日休み（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"
}

例2: 営業時間内（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
}

例3: country なし（祝日考慮なし）

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

タイムゾーン間の日時変換とスケジュール計算を行います。サマータイム（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タイムスタンプ・曜日付きで返します。外部依存なし・datetime.is_holidayやdatetime.add_business_daysと組み合わせることでエージェントが現在時刻を起点に確実に計算できます。

MCPツール名: datetime.get_current_datetime

GET /v1/datetime/now

パラメータ:

パラメータ	型	必須	説明
timezone	string	-	IANAタイムゾーン（デフォルト: Asia/Tokyo）
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ツール名: datetime.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）。省略時は Asia/Tokyo

リクエスト例:

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

POST /v1/cron/laravel

Laravel のスケジューラ式（`dailyAt()`、`weeklyOn()`、`between()` など）を Cron 式に変換し、次回実行時刻を返します。`app/Console/Kernel.php` の定義をアプリを起動せずに検証できます。

MCPツール名: datetime.parse_laravel_schedule

パラメータ:

パラメータ	型	必須	説明
expression	string	✓	Laravel スケジュール式（例: dailyAt('03:30')）
base_datetime	string	-	基準日時（ISO 8601）。省略時は現在時刻
timezone	string	-	IANAタイムゾーン（デフォルト: Asia/Tokyo）
count	integer	-	次のN回分を返す（1〜10、デフォルト3）

レスポンスフィールド

パラメータ	型	説明
expression	string	入力した Laravel 式
cron_equivalent	string	変換後の Cron 式（5フィールド）
timezone	string	使用したタイムゾーン
between_start	string	between() 指定時の開始時刻（HH:MM）
between_end	string	between() 指定時の終了時刻（HH:MM）
next_runs	string[]	次回実行時刻（ISO 8601、オフセット付き）

対応メソッド一覧（Laravel 式 → Cron 式）

パラメータ	型	説明
everyMinute()	* * * * *	毎分
everyFiveMinutes()	/5 * * *	5分ごと
hourly()	0 * * * *	毎時0分
hourlyAt(17)	17 * * * *	毎時17分
daily()	0 0 * * *	毎日0:00
dailyAt('13:00')	0 13 * * *	毎日13:00
twiceDaily(1, 13)	0 1,13 * * *	毎日1時と13時
weekly()	0 0 * * 0	毎週日曜0:00
weeklyOn(1, '8:00')	0 8 * * 1	毎週月曜8:00
monthly()	0 0 1 * *	毎月1日0:00
monthlyOn(4, '15:00')	0 15 4 * *	毎月4日15:00
quarterly()	0 0 1 1,4,7,10 *	四半期ごと
yearly()	0 0 1 1 *	毎年1月1日
cron('* * * * *')	（そのまま）	任意の Cron 式

基本例: 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"
  ]
}

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

応用: cron_equivalent を 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"

日時差分計算

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

MCPツール名: datetime.calc_datetime_diff

GET /v1/datetime/diff

パラメータ:

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

リクエスト例:

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

相対時刻フォーマット

絶対日時（ISO 8601）を「3時間前」「昨日」などの相対・自然言語表現に変換します。ログ・通知・チャットUI向けの人間可読ラベルをロケール正しく生成します。

MCPツール名: datetime.format_relative_time

GET /v1/datetime/relative

パラメータ:

パラメータ	型	必須	説明
datetime	string	✓	対象日時（ISO 8601）
reference	string	-	基準日時（省略時はサーバー現在時刻）
locale	string	-	BCP 47 ロケール（デフォルト: ja-JP）
style	string	-	long / short / narrow（デフォルト: long）
timezone	string	-	IANA タイムゾーン（デフォルト: Asia/Tokyo）

リクエスト例:

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"

レスポンス例:

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

和暦↔西暦変換

和暦（元号）と西暦日付を相互変換します。明治・大正・昭和・平成・令和に対応し、平成→令和（2019-04-30 / 2019-05-01）や昭和→平成（1989-01-07 / 1989-01-08）など元号境界日を正確に処理します。

MCPツール名: datetime.convert_japanese_era

GET /v1/datetime/era/convert

パラメータ（direction=to_gregorian）:

パラメータ	型	必須	説明
direction	string	✓	to_gregorian
era	string	✓	元号名（reiwa / heisei / showa / taisho / meiji または令和 / 平成等）
era_year	integer	✓	和暦年（1始まり。元年 = 1）
month	integer	-	月（1-12、デフォルト: 1）
day	integer	-	日（1-31、デフォルト: 1）

パラメータ（direction=to_japanese_era）:

パラメータ	型	必須	説明
direction	string	✓	to_japanese_era
date	string	✓	西暦日付（YYYY-MM-DD）

レスポンスフィールド（direction=to_gregorian）:

パラメータ	型	説明
direction	string	to_gregorian
input	object	リクエスト入力（era, era_year, month?, day?）
output.date	string	西暦日付（YYYY-MM-DD）
output.year	integer	西暦年
output.month	integer	月
output.day	integer	日
era_label_ja	string	元号の日本語表記（例: 令和）
era_label_en	string	元号の英語表記（例: Reiwa）

レスポンスフィールド（direction=to_japanese_era）:

パラメータ	型	説明
direction	string	to_japanese_era
input	object	リクエスト入力（date）
output.era	string	元号コード（reiwa / heisei 等）
output.era_year	integer	和暦年（1始まり）
output.year_label	string	和暦年ラベル（例: 令和7年 / 令和元年）
output.month	integer	月
output.day	integer	日
era_label_ja	string	元号の日本語表記
era_label_en	string	元号の英語表記

対応元号一覧:

パラメータ	型	説明
明治 (meiji)	1868-01-25	1912-07-29
大正 (taisho)	1912-07-30	1926-12-24
昭和 (showa)	1926-12-25	1989-01-07
平成 (heisei)	1989-01-08	2019-04-30
令和 (reiwa)	2019-05-01	継続中

例1: 和暦→西暦（令和7年5月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"
}

例2: 西暦→和暦（2019-04-30 = 平成31年・平成最終日）

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

例3: 西暦→和暦（2019-05-01 = 令和元年・令和初日）

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

ISO 8601 Duration変換

ISO 8601 Duration 文字列（例: PT1H30M、P1DT2H）を成分（日・時・分・秒）と合計秒数に分解するか、成分から ISO 8601 文字列を生成します。S3 プリサインド URL の有効期限、JWT の exp 計算、タイムアウト設定などで PT1H・3600秒・「1時間」が混同されるミスを防ぎます。

MCPツール名: datetime.convert_iso_duration

POST /v1/datetime/duration/convert

パラメータ（direction=parse）:

パラメータ	型	必須	説明
direction	string	✓	parse
duration	string	✓	ISO 8601 duration 文字列（例: PT1H30M45S）
include_months_years	boolean	-	年・月を含む場合に近似変換を許可（デフォルト: false）

パラメータ（direction=format）:

パラメータ	型	必須	説明
direction	string	✓	format
days	number	-	日（0以上）
hours	number	-	時（0以上）
minutes	number	-	分（0以上）
seconds	number	-	秒（0以上、小数可・小数点以下3桁まで）
years	number	-	年（include_months_years=true 時）
months	number	-	月（include_months_years=true 時）
include_months_years	boolean	-	年・月成分を含める場合に true（デフォルト: false）

レスポンスフィールド（direction=parse）:

パラメータ	型	説明
direction	string	parse
input	string	入力された duration 文字列
output.days	number	日
output.hours	number	時
output.minutes	number	分
output.seconds	number	秒
output.total_seconds	number	合計秒数（年・月は近似加算）
output.years	number	年（含む場合のみ）
output.months	number	月（含む場合のみ）
iso_duration	string	正規化された ISO 8601 文字列
warnings	string[]	年・月を含む場合の警告（任意）

レスポンスフィールド（direction=format）:

パラメータ	型	説明
direction	string	format
input	object	リクエスト入力（成分）
output	string	生成された ISO 8601 duration 文字列
total_seconds	number	合計秒数
warnings	string[]	年・月を含む場合の警告（任意）

例1: parse — PT1H30M45S を成分・秒数に分解

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

例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
}

例3: include_months_years=true — P1Y6M を許容して 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."
  ]
}