ForHosting KIT · 開発者向けツール

日時を小数年へ変換

小数年変換では、明示されたISO 8601日時を2024.5のような小数表記の年へ変換します。まず指定されたタイムゾーンのオフセットをUTCに正規化し、そのUTC年の開始から経過した正確なミリ秒を年全体の長さで割ります。整数部はUTC年を示し、小数部はその年の中での時点の位置を示します。現在時刻、場所、ネットワーク、暗黙の既定値は参照しないため、同じ入力からは常に同じ結果が得られます。

● Beta無料・ブラウザ内で実行

無料で実行 API仕様を見る

ご利用方法ウェブAPIメールTelegramアプリ近日

小数年が表す内容

小数年は、暦年の番号と、その年の中の連続した位置を1つの数値にまとめたものです。整数部は、指定された時点を含むUTC暦年です。小数部は、1月1日00:00:00.000 UTCから経過した正確な時間を、その年全体の長さで割った値です。そのため、2024年の最初の時点は正確に2024となり、うるう年である同年の中間点は2024.5となります。2024年末には結果が2025へ近づきますが到達せず、2025年の最初の時点から新しい年に属して正確に2025となります。この定義は経過時間に基づき、カレンダーのページ、完了した日付、月、四半期、営業日を数えるものではありません。時、分、秒、ミリ秒もそれぞれの割合で反映されます。応答には、UTCへ正規化した日時、選択されたUTC年、経過ミリ秒、年全体のミリ秒が含まれます。したがって、タイムスタンプよりも簡潔な年座標が必要な場合でも、暦年を保ったまま各要素を確認し、計算を独立して検証できます。

UTC正規化とうるう年による違い

入力は、Zまたは+05:30や-04:00のような数値オフセットで実在する時点を特定する必要があります。変換処理では、年の選択と経過時間の測定より先にオフセットを適用します。この順序は年境界で重要です。1月1日の深夜直後を示す現地時刻でもUTCではまだ12月31日の場合があり、逆に12月末の遅い現地時刻がUTCではすでに1月1日の場合もあります。その後、得られたUTC年にグレゴリオ暦のうるう年規則を適用します。4で割り切れる年は366日ですが、400で割り切れない世紀年は除外され、その他は365日です。選択された年に応じて分母が変わるため、すべての年を固定365日とみなすずれを防げます。各暦日は正確に86,400秒として扱い、うるう秒は挿入しません。パーサーは、オフセットの欠落や不正、存在しない日付、平年のうるう日、23を超える時、59を超える分や秒、3桁を超えるミリ秒を拒否します。タイムゾーンを推測して補正すると環境間の再現性が失われるため、曖昧な入力は拒否します。

データ処理や科学的ワークフローでの利用

小数年は、複数の暦年に分布する観測値を表す簡潔な座標として利用できます。時系列パイプラインでは、オフセット付きタイムスタンプを回帰、補間、作図、エクスポートの前に変換し、元のタイムスタンプを別に保持しながら各レコードへ並べ替え可能な数値を付与できます。科学報告では年軸上に測定値を配置するために小数年がよく使われ、移行処理では旧分析システムの値を再現する必要もあります。決定論的な応答はテストにも適しており、現在時刻を模擬せずに、年始、うるう日、中間点、オフセットによる年越し、年末最後のミリ秒を固定できます。他のシステムでは日数、正午基準、固定365.25日年、異なる丸め規則を採用する場合があるため、定義をデータと一緒に保存してください。この機能は、正確なUTC経過ミリ秒を、該当する先発グレゴリオ暦UTC年の正確な長さで割ります。途中では丸めず、図表や報告の表示時だけ丸めてください。可逆変換や極めて近い時点の厳密な順序が必要な場合は、絶対タイムスタンプの代わりに使用しないでください。成功したAPI計算の料金は$0.002で、同じ純粋な計算をブラウザーでも実行できます。

活用例

時系列観測値の正規化

オフセット付き日時を、作図、回帰、補間に使える連続した小数年座標へ変換します。

科学報告の年軸を再現

文書化されたUTCグレゴリオ暦の年長規則により、検証可能な小数年を生成します。

決定論的な日付テストを作成

現在のシステム時刻を参照または模擬せず、うるう年やタイムゾーンによる年越しをテストします。

よくある質問

どの計算式を使用しますか？

UTC年に、その年の開始からの経過ミリ秒を同じUTC年の総ミリ秒で割った値を加えます。

日時にタイムゾーンが必要なのはなぜですか？

Zまたは数値オフセットがない文字列は1つの時点を特定できず、環境によって結果が変わる可能性があるためです。

うるう年はどのように扱いますか？

対象のUTC年がグレゴリオ暦のうるう年なら366日、それ以外は365日として計算します。

うるう秒は含まれますか？

含まれません。移植可能で決定論的な結果を得るため、各暦日を正確に86,400秒として扱います。

API計算の料金はいくらですか？

成功したAPIリクエスト1回の料金は$0.002です。純粋な計算はブラウザー内でも実行できます。

開発者向け — APIアクセス

このページの機能はすべてAPIからも利用できます。自社システムに組み込みたいチーム向けのセクションです。それ以外の方は上のツールをそのままお使いください。

エンドポイント

POSThttps://api.kit.forhosting.com/date/fractional-year

Bearerトークンで認証し、POST1回でタスクをキューに登録します。結果はWebhookまたは署名付きリンクで受け取れます。

お使いのスタックから呼び出す

curl -X POST https://api.kit.forhosting.com/date/fractional-year \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime":"2024-07-02T00:00:00Z"}'

const res = await fetch("https://api.kit.forhosting.com/date/fractional-year", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "datetime": "2024-07-02T00:00:00Z"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/date/fractional-year",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "datetime": "2024-07-02T00:00:00Z"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/fractional-year", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"datetime":"2024-07-02T00:00:00Z"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"datetime":"2024-07-02T00:00:00Z"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/fractional-year", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

リクエスト例

{
  "datetime": "2024-07-02T00:00:00Z"
}

レスポンス例

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "date.fractional_year",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

非同期APIです。task_idは即時に返ります。ポーリングは1秒あたり1リクエストまでです。

料金

1リクエストあたり$0.002

単価はすべて公開しています。トークン換算や独自クレジットはありません。失敗したタスクは課金されません。

エラー

HTTP	コード	意味
`401`	`unauthorized`	APIキーが無効か、指定されていません。Authorizationヘッダーを確認してください。
`402`	`insufficient_balance`	残高が不足しています。チャージ後に再度お試しください。
`404`	`unknown_type`	指定されたタスクタイプは存在しません。タイプ名を確認してください。
`429`	`rate_limited`	リクエストが多すぎます。しばらく待ってから再度お試しください。

KITの完全なドキュメントを見る →