وقت

برای برنامه‌نویسان

تقویم و وقت افغانستان برای برنامهٔ شما

تقویم‌های شمسی و قمری، نام ماه‌ها به هفت زبان، و طلوع و غروب آفتاب در مرکز هر ولایت: چند فایل ساده و یک مادیول JavaScript. بدون کلید و بدون ثبت‌نام.

نسخهٔ ۱JSON و JavaScriptنمونه‌ها به JavaScript و PHP

در این صفحه

به‌طور خلاصههمهٔ فایل‌ها در waqt.qudqu.com/api/v1/ هستند و از هر سایتی باز می‌شوند. هر فایل از همان کودی ساخته می‌شود که این سایت به کار می‌برد، پس API و سایت هیچ‌گاه دو تاریخ مختلف نمی‌دهند. هیچ نام ماه ایرانی در آن‌ها نیست.

شروع سریع

یک خط import در یک <script type="module"> کافی است: نه نصب، نه کلید، نه ثبت‌نام. این کود همین حالا در مرورگر شما اجرا شد؛ جواب امروز زیر هر خط است.

quick-start.htmlHTML
همین حالا اجرا شد
<script type="module">
	import { Calendar, Language, formatDate, wallTime }
		from 'https://waqt.qudqu.com/api/v1/waqt.js';

	// Today on Afghan time, as a day number
	const today = wallTime(Date.now()).day;

	console.log(formatDate(today, Calendar.SHAMSI, Language.DARI).text);
	// → …
	console.log(formatDate(today, Calendar.QAMARI, Language.PASHTO).text);
	// → …
	console.log(formatDate(today, Calendar.GREGORIAN, Language.ENGLISH).text);
	// → …
</script>

فایل‌ها

فایلچه دارداندازه
calendar.jsonجدول سال‌های شمسی و قمری، تعریف شمارهٔ روز، وقت افغانستان۳ کیلوبایت
names.jsonنام ماه‌های سه تقویم، روزهای هفته و رقم‌ها، به هفت زبان۳ کیلوبایت
places.json۳۴ مرکز ولایت: مختصات، نام شهر و ولایت به هفت زبان۴ کیلوبایت
sun/kabul.jsonوقت آفتاب برای هر روز سال شمسی؛ یک فایل برای هر مرکز ولایت۴ کیلوبایت
waqt.jsمادیول JavaScript: تبدیل و نوشتن تاریخ، وقت افغانستان، آفتاب و مهتاب۲۰ کیلوبایت
اندازه‌ها فشرده (gzip)، همان‌طور که مرورگر دریافت می‌کند. هر فایل JSON در بخش description خود می‌گوید که چگونه خوانده شود.

تبدیل تاریخ با شمارهٔ روز

هر تاریخ یک شمارهٔ روز دارد: شمار روزها از اول جنوری ۱۹۷۰. هر سه تقویم به شمارهٔ روز و از آن تبدیل می‌شوند، پس یک تاریخ از راه شمارهٔ روز از یک تقویم به تقویم دیگر می‌رود.

مادیول این کار را با یک فنکشن می‌کند. بدون مادیول هم ساده است: در calendar.json آخرین سالی را پیدا کنید که پیش از آن روز یا در همان روز شروع می‌شود، بعد ماه‌ها را بشمارید.

import {
	Calendar, Digits, HijriAdjustment, Language,
	formatDate, fromGregorian, fromShamsi,
	toGregorian, toQamari, toShamsi, wallTime
} from 'https://waqt.qudqu.com/api/v1/waqt.js';

// A date is a day number: whole days since 1 January 1970
const nowruz = fromGregorian(2026, 3, 21);
console.log(nowruz);
// → 20533
console.log(toShamsi(nowruz));
// → { year: 1405, month: 1, day: 1 }
console.log(toQamari(nowruz));
// → { year: 1447, month: 10, day: 2 }
console.log(toGregorian(fromShamsi(1404, 12, 29)));
// → { year: 2026, month: 3, day: 20 }

// If the month began a day later in Afghanistan than in Umm al-Qura
console.log(toQamari(nowruz, HijriAdjustment.DAY_LATER));
// → { year: 1447, month: 10, day: 1 }

// As text, in any of the seven languages
console.log(formatDate(nowruz, Calendar.SHAMSI, Language.DARI).text);
// → ۱ حمل ۱۴۰۵
console.log(formatDate(nowruz, Calendar.SHAMSI, Language.PASHTO).text);
// → ۱ وری ۱۴۰۵
console.log(formatDate(nowruz, Calendar.QAMARI, Language.ENGLISH).text);
// → 2 Shawwal 1447

// With the weekday, in Latin digits
const options = { weekday: true, digits: Digits.LATIN };
console.log(formatDate(nowruz, Calendar.SHAMSI, Language.DARI, options).text);
// → شنبه، 1 حمل 1405

// Today, on Afghan time
const today = wallTime(Date.now()).day;
console.log(formatDate(today, Calendar.QAMARI, Language.DARI).text);

تاریخ قمری و دیدن هلال

جدول قمری از تقویم ام‌القری است. در افغانستان ماه قمری با دیدن هلال شروع می‌شود، و این را از پیش نمی‌توان حساب کرد: تاریخ گاهی یک روز با جدول فرق می‌کند. اگر ماه یک روز دیرتر از جدول شروع شد، جدول را در روز پیش بخوانید (شمارهٔ روز منهای ۱)؛ اگر یک روز زودتر، در روز بعد. فنکشن‌های مادیول همین را به شکل HijriAdjustment.DAY_LATER یا HijriAdjustment.DAY_EARLIER می‌گیرند.

نام ماه‌ها و روزها به هفت زبان

names.json برای هر زبان نام ماه‌های سه تقویم، روزهای هفته از شنبه، «قبل از ظهر» و «بعد از ظهر»، نام تقویم‌ها و رقم‌های آن زبان را دارد. پشتو نام‌های خود را دارد؛ زبان‌های دیگر نام‌های دری را به خط خود می‌نویسند.

هیچ نام ماه ایرانی در این فایل‌ها نیست، و تست‌های ما هر روز را در هر زبان می‌سنجند. نام‌ها را از این فایل بگیرید، نه از مرورگر: بسیاری از مرورگرها برای افغانستان نام‌های ایرانی نشان می‌دهند.

names.jsonJSON
{
  "languages": {
    "fa": {
      "months": {
        "shamsi": [
          "حمل", "ثور", "جوزا", "سرطان", "اسد", "سنبله",
          "میزان", "عقرب", "قوس", "جدی", "دلو", "حوت"
        ],
        "qamari": ["محرم", …],
        "gregorian": ["جنوری", …]
      },
      "weekdays": [
        "شنبه", "یکشنبه", "دوشنبه", "سه‌شنبه",
        "چهارشنبه", "پنجشنبه", "جمعه"
      ],
      "digits": "۰۱۲۳۴۵۶۷۸۹",
      …
    },
    "ps": {
      "months": {
        "shamsi": [
          "وری", "غویی", "غبرګولی", "چنګاښ", "زمری", "وږی",
          "تله", "لړم", "لیندۍ", "مرغومی", "سلواغه", "کب"
        ],
        "qamari": ["محرم", …],
        "gregorian": ["جنوري", …]
      },
      "weekdays": [
        "شنبه", "یکشنبه", "دوشنبه", "سه شنبه",
        "چهارشنبه", "پنجشنبه", "جمعه"
      ],
      "digits": "۰۱۲۳۴۵۶۷۸۹",
      …
    },
    "en": { "months": { "shamsi": ["Hamal", "Sawr", "Jawza", …] }, … },
    …
  }
}

طلوع و غروب آفتاب

برای هر مرکز ولایت یک جدول هست: روشنی صبح، طلوع، ظهر آفتابی، غروب، تاریکی شب و درازی روز، برای هر روز سال شمسی، به وقت افغانستان. جدول برای هر سال درست است، با کمتر از ۲ دقیقه فرق، چون سال شمسی با آفتاب می‌رود.

برای دقیقهٔ دقیق یک سال، یا برای هر جای دیگر، فنکشن sunDay را به کار ببرید. فورمول آن به PHP هم اینجاست.

// A sun table needs no code: months[m - 1][d - 1] is Shamsi month m, day d
const url = 'https://waqt.qudqu.com/api/v1/sun/herat.json';
const table = await (await fetch(url)).json();
console.log(table.columns);
// → [ 'firstLight', 'sunrise', 'noon', 'sunset', 'dark', 'dayLength' ]
console.log(table.months[0][0]); // 1 Hamal
// → [ '05:30', '06:25', '12:29', '18:33', '19:27', '12:08' ]

مهتاب

مادیول جای مهتاب در آسمان هر جا، اندازهٔ روشن آن، طلوع و غروب آن در هر روز، و وقت ماه نو و ماه تمام بعدی را می‌دهد. برای دیدن هلال اول ماه نیست.

moon.jsJavaScript
import {
	MoonPhase, moonState, nextMoonPhase
} from 'https://waqt.qudqu.com/api/v1/waqt.js';

// The moon over Kabul on an evening (or moonState(ms, latitude, longitude))
const evening = Date.parse('2026-03-21T19:00:00+04:30');
const moon = moonState(evening);

// Percent lit, and days since the new moon
console.log(Math.round(moon.lit * 100), moon.age.toFixed(1));
// → 9 2.8

const full = nextMoonPhase(evening, MoonPhase.FULL);
console.log(new Date(full).toISOString().slice(0, 16));
// → 2026-04-02T02:14

نسخهٔ ۱: آنچه تغییر نمی‌کند

  • شکل فایل‌ها ثابت است. ممکن است چیزی به آن‌ها اضافه شود، اما هیچ نامی برداشته یا عوض نمی‌شود. تغییری که به این قاعده صدق نکند، /api/v2/ می‌شود و نسخهٔ ۱ می‌ماند.
  • از ۱ جنوری ۱۹۰۰ تا ۲۵ نومبر ۲۱۷۴ (۱۲۷۸ تا ۱۵۵۳ شمسی، ۱۳۱۷ تا ۱۶۰۰ قمری). بیرون از این، فنکشن‌ها خطا می‌دهند.
  • از هر سایتی. فایل‌ها با Access-Control-Allow-Origin: * فرستاده می‌شوند، و مرورگرها ۱۰ دقیقه نگه‌شان می‌دارند.
  • بدون آمار و کوکی. فایل‌ها هیچ کوکی نمی‌گذارند و هیچ آماری جمع نمی‌کنند.

شرایط استفاده

مجوز: CC BY 4.0

اشتباهی دیدید، یا چیزی کم است؟ به ما بنویسید.