Waqt

Для разработчиков

Афганские даты и время для вашей программы

Календари шамси и камари, названия месяцев на семи языках, восход и закат в центре каждой провинции: несколько простых файлов и один модуль JavaScript. Без ключа и без регистрации.

Версия 1JSON и 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Таблицы лет шамси и камари, что такое номер дня, афганское время3 КБ
names.jsonМесяцы трёх календарей, дни недели и цифры на семи языках3 КБ
places.json34 центра провинций: координаты, названия города и провинции на семи языках4 КБ
sun/kabul.jsonСолнце в каждый день года шамси; по файлу на каждый центр провинции4 КБ
waqt.jsМодуль JavaScript: перевод и запись дат, афганское время, солнце и луна20 КБ
Размеры в сжатом виде (gzip), как их получает браузер. Каждый файл JSON говорит в своём description, как его читать.

Перевод дат через номер дня

У каждой даты есть номер дня: число дней с 1 января 1970 года. Все три календаря переводятся в номер дня и обратно, поэтому дата переходит из одного календаря в другой через свой номер дня.

Модуль делает это одной функцией. Без модуля это тоже просто: найдите в 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);

Даты камари и наблюдение луны

Таблица камари взята из календаря Умм аль-Кура. В Афганистане месяц камари начинается, когда видят новый серп луны, а это нельзя рассчитать заранее: дата иногда расходится с таблицей на день. Если месяц начался на день позже, чем в таблице, читайте таблицу на день раньше (номер дня минус 1); если на день раньше, то на день позже. Функции модуля принимают то же самое как 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", …] }, … },
    …
  }
}

Восход и закат

Для каждого центра провинции есть таблица: первый свет, восход, полдень, закат, темнота и долгота дня, на каждый день года шамси, по афганскому времени. Таблица верна для любого года с точностью до 2 минут, потому что год шамси идёт за солнцем.

Для точной минуты в конкретном году или для любого другого места используйте 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

Версия 1: что не меняется

  • Файлы сохраняют свою форму. В них может что-то добавиться, но ни одно имя не будет удалено или изменено. Изменение, которое не укладывается в это правило, станет /api/v2/, а версия 1 останется.
  • С 1 января 1900 по 25 ноября 2174 года (шамси с 1278 по 1553, камари с 1317 по 1600). За этими пределами функции выдают ошибку.
  • С любого сайта. Файлы отправляются с Access-Control-Allow-Origin: *, и браузеры хранят их 10 минут.
  • Без статистики и cookie. Файлы не ставят cookie и не собирают статистику.

Лицензия

Лицензия: CC BY 4.0

Заметили ошибку или чего-то не хватает? Напишите нам.