ForHosting KIT · 開発者向けツール

年間経過割合

この年間進捗計算では、明示されたISO 8601日時の時点でUTC暦年が経過した割合を返します。Zまたは数値オフセット付きの時刻をUTCに変換し、1月1日00:00:00 UTCからの正確な経過ミリ秒を、変換後のUTC年全体のミリ秒数で割ります。うるう年は366日、平年は365日として扱います。現在日時、端末のタイムゾーン、ネットワーク、乱数、暗黙の既定値は結果に影響しません。そのため、同じ入力からはどの環境でも同じ値が得られます。

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

無料で実行 API仕様を見る

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

年間経過割合が表すもの

返される値は、1つのUTC暦年の進み具合を連続量で示します。分子は1月1日00:00:00.000 UTCから指定された瞬間までのミリ秒数、分母はそのUTC年全体のミリ秒数です。1月1日の最初の瞬間では結果が正確にゼロになります。その後は年内で増え続けますが、その年に属する有効な日時では常に1未満です。1になるはずの瞬間は翌年の最初の瞬間であり、すでに新しい年に属するため、そこで計算値は再びゼロになります。これは、日付を丸一日単位で数えたり、当日がすべて経過したものとして扱ったりする通算日ベースの割合とは異なります。正午ならその日の半分が加わり、秒も正確に反映され、小数秒は最大3桁までミリ秒として保持されます。分母は平年で365日、グレゴリオ暦のうるう年で366日です。UTC年を選ぶ前にオフセットを正規化するため、別のタイムゾーンで12月31日深夜と記された瞬間が、UTCでは翌年1月1日に正しく属する場合もあります。

曖昧さのないISO日時の入力方法

datetimeにはYYYY-MM-DDTHH:mm:ssZ形式を指定してください。秒には1桁から3桁の小数部を追加でき、Zの代わりに+05:30や-04:00のような符号付き数値オフセットも指定できます。タイムゾーン表記がない日時は一意の瞬間を示さないため、指定は必須です。日付だけの値、地域固有の書式、月名、Tの代わりの空白、コロンのないオフセットは推測せずに拒否します。パーサーは、グレゴリオ暦の月の日数、うるう日、時、分、秒、オフセットの各項目も検証します。うるう秒には対応せず、秒は00から59までです。これは計算で用いる決定論的な常用時の分モデルに合わせた仕様です。解析後は整数演算でオフセットを適用し、変換後の瞬間をutc_datetimeとして返します。さらにutc_year、elapsed_milliseconds、year_millisecondsも返すため、暦規則を再実装せずに割合を検証できます。異なるオフセットで同じ瞬間を表す2つの文字列は、同じ正規化日時と割合になります。自動化した正常なAPIリクエストは1回$0.002で、ブラウザー内でも計算できます。

決定論的な年間比率の活用場面

モデル、可視化、レポート、テストで、実行時刻に左右されない安定した暦年内の位置が必要な場合にご利用ください。ダッシュボードでは、正確な分子と分母をラベルや監査用に保持しながら、割合をパーセントや進捗バーへ変換できます。データ処理では、明示オフセット付きの入力を同じUTC時間軸で比較し、季節分析、補間、周期特徴量に用いる正規化済み年間座標をタイムスタンプ付きレコードへ追加できます。テストでは時計を模擬せずに、年始、うるう日、12月最後のミリ秒といった境界条件を固定できます。結果は経過時間に基づくため、完了した暦日の数、営業日、会計期間、同じ長さとみなした月の計算には適しません。また、UTCの常用日を意図的に86,400秒として扱い、うるう秒を挿入しないため、環境を問わず再現できます。パーセントが必要な場合はfractionを100倍し、表示時にだけ丸めてください。会計年度の比率には、その会計暦の境界を使う別の計算が必要です。

活用例

年間進捗ダッシュボード

明示したタイムスタンプをUTC年内のゼロから1までの正確な位置へ変換し、進捗バーやKPI表示に利用できます。

季節分析用の特徴量

明示オフセットをUTCに正規化した後、タイムスタンプ付きレコードへ一貫した連続年間座標を追加できます。

境界条件の決定論的テスト

システム時計を参照または模擬せず、年始やうるう日前後の再現可能なテストデータを作成できます。

よくある質問

割合が1になることはありますか？

選択されたUTC年内の瞬間では1になりません。翌年の最初の瞬間は新しい年に属するため、ゼロを返します。

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

UTC年が4で割り切れる場合は366日を使います。ただし400で割り切れない世紀年を除き、それ以外は365日です。

タイムゾーンが必須なのはなぜですか？

Zまたは数値オフセットがないローカルISO日時は一意のUTC瞬間を示さず、環境によって結果が変わる可能性があるためです。

うるう秒も計算に含まれますか？

含まれません。常用日を86,400秒に固定し、秒は00から59までとして、移植可能で決定論的な暦年比率を算出します。

APIリクエストの料金はいくらですか？

正常なAPI計算は1回$0.002です。同じ純粋な計算をブラウザー内でも利用できます。

開発者向け — APIアクセス

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

エンドポイント

POSThttps://api.kit.forhosting.com/date/fraction-of-year-elapsed

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

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

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

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

import os, requests

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

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

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

リクエスト例

{
  "datetime": "2026-07-02T12:00:00Z"
}

レスポンス例

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "date.fraction_of_year_elapsed",
  "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の完全なドキュメントを見る →