ڈیولپرز کے لیے

ایک مفت ٹائم زون API

وہی انجن جو Hourora کو چلاتا ہے، سادہ JSON کی شکل میں: کہیں کا بھی وقت، ڈے لائٹ سیونگ کو سمجھنے والی تبدیلیاں، ہر IANA زون اور اس کی گھڑیوں کی تبدیلیاں۔ نہ key، نہ سائن اپ۔

ایک نظر میں

بنیادی URL: https://hourora.app/api/v1
فارمیٹ: JSON (UTF-8)، صرف GET درخواستیں
تصدیق: کوئی نہیں: نہ key، نہ سائن اپ، نہ کوکیز
CORS: ہر origin کے لیے کھلا، اس لیے آپ اسے براؤزر سے کال کر سکتے ہیں
ریٹ لمٹ: فی کلائنٹ فی منٹ 120 درخواستیں
وقت کا ڈیٹا: IANA tzdata 2026e، Hourora کا مرتب کردہ
مشین کے پڑھنے کے قابل وضاحت: OpenAPI 3.1 دستاویز

براہِ راست آزمائیں

کوئی مثال منتخب کریں یا path میں ترمیم کریں، پھر اسے بھیجیں۔ درخواست آپ کے براؤزر سے سیدھی API تک جاتی ہے۔

جواب

جواب یہاں ظاہر ہوگا۔

اینڈ پوائنٹس

ہر اینڈ پوائنٹ GET کا جواب JSON میں دیتا ہے۔ اوقات ISO 8601 میں ہیں؛ آفسیٹ UTC سے مشرق کی جانب منٹوں میں ہیں (سردیوں میں نیویارک −300 ہے) اور متن کی صورت میں بھی لکھے جاتے ہیں (−05:00)۔

موجودہ وقت

GET/api/v1/time

کسی ٹائم زون یا شہر کا موجودہ وقت: مقامی وقت، UTC آفسیٹ، مخفف، ڈے لائٹ سیونگ اور گھڑیوں کی اگلی تبدیلی۔ پیرامیٹرز کے بغیر: UTC۔

پیرامیٹرز

نام	مطلب
`tz`اختیاری	IANA ٹائم زون کا نام، مثلاً Europe/London۔ Asia/Calcutta جیسے متبادل نام قبول کیے جاتے ہیں اور جواب موجودہ نام کے ساتھ دیا جاتا ہے۔
`city`اختیاری	tz کے بجائے شہر کا slug، مثلاً london (slugs ‎/cities سے تلاش کریں)۔

مثالی درخواست

curl "https://hourora.app/api/v1/time?tz=Europe/London"

مثالی جواب

{
  "zone": "Europe/London",
  "local": "2026-10-15T12:42:01",
  "iso": "2026-10-15T12:42:01+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-15T11:42:01.270Z",
  "unixMs": 1792064521270,
  "date": "2026-10-15",
  "time": "12:42:01",
  "weekday": "Thursday",
  "dayOfYear": 288,
  "isoWeek": 42,
  "dstObserved": true,
  "nextTransition": {
    "at": "2026-10-25T01:00:00.000Z",
    "unixMs": 1792890000000,
    "type": "dst-end",
    "fromOffsetMinutes": 60,
    "toOffsetMinutes": 0,
    "shiftMinutes": -60,
    "fromAbbreviation": "BST",
    "toAbbreviation": "GMT",
    "localBefore": "2026-10-25T02:00:00",
    "localAfter": "2026-10-25T01:00:00"
  },
  "tzdata": "2026e"
}

اس سرور کا حقیقی جواب۔

وقت تبدیل کریں

GET/api/v1/convert

ایک زون کی گھڑی کا وقت دوسرے زون میں۔ بتاتا ہے کہ کب وقت ڈے لائٹ سیونگ کے خلا (gap، جب وہ موجود ہی نہیں) یا اوورلیپ (overlap، جب وہ دو بار آتا ہے) میں آتا ہے۔

پیرامیٹرز

نام	مطلب
`from`لازمی	وہ زون (یا شہر کا slug) جس میں وقت پڑھا جاتا ہے۔
`to`لازمی	وہ زون (یا شہر کا slug) جس میں اسے دکھانا ہے۔
`time`اختیاری	from زون میں گھڑی کا وقت، YYYY-MM-DDTHH:mm (سیکنڈ اختیاری، آفسیٹ کے بغیر)، 1970–2060۔ ڈیفالٹ: ابھی۔

مثالی درخواست

curl "https://hourora.app/api/v1/convert?from=America/New_York&to=Asia/Kolkata&time=2026-10-16T15:00"

مثالی جواب

{
  "status": "ok",
  "requested": "2026-10-16T15:00:00",
  "utc": "2026-10-16T19:00:00.000Z",
  "unixMs": 1792177200000,
  "from": {
    "zone": "America/New_York",
    "local": "2026-10-16T15:00:00",
    "iso": "2026-10-16T15:00:00-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true
  },
  "to": {
    "zone": "Asia/Kolkata",
    "local": "2026-10-17T00:30:00",
    "iso": "2026-10-17T00:30:00+05:30",
    "offsetMinutes": 330,
    "offset": "+05:30",
    "utcOffset": "UTC+5:30",
    "abbreviation": "IST",
    "dst": false,
    "dayOffset": 1
  },
  "differenceMinutes": 570,
  "tzdata": "2026e"
}

اس سرور کا حقیقی جواب۔

ٹائم زونز کی فہرست

GET/api/v1/zones

ہر IANA ٹائم زون، اس کے موجودہ UTC آفسیٹ، مخفف، ڈے لائٹ سیونگ کی حالت، ممالک اور مرکزی شہر کے ساتھ۔

پیرامیٹرز

نام	مطلب
`country`اختیاری	ISO 3166 ملکی کوڈ، مثلاً GB، صرف اسی ملک کو رکھنے کے لیے۔

مثالی درخواست

curl "https://hourora.app/api/v1/zones?country=GB"

مثالی جواب

{
  "asOf": "2026-10-15T11:42:01.270Z",
  "count": 1,
  "tzdata": "2026e",
  "zones": [
    {
      "id": "Europe/London",
      "offsetMinutes": 60,
      "offset": "+01:00",
      "utcOffset": "UTC+1",
      "abbreviation": "BST",
      "dst": true,
      "countries": [
        "GB",
        "GG",
        "IM"
      ],
      "mainCity": "London"
    }
  ]
}

اس سرور کا حقیقی جواب؛ فہرستیں پہلے 3 آئٹمز تک مختصر کی گئی ہیں۔

ایک ٹائم زون

GET/api/v1/zones/{id}

ایک IANA زون: اس کے متبادل نام (aliases)، ممالک اور شہر، اس کا موجودہ آفسیٹ، گھڑیوں کی اگلی تبدیلی اور کسی مخصوص سال کی ہر تبدیلی۔

پیرامیٹرز

نام	مطلب
`id`path میں	IANA زون کا نام؛ سلیش برقرار رکھیں یا اسے %2F کے طور پر encode کریں۔
`year`اختیاری	وہ سال جس کی گھڑیوں کی تبدیلیاں درج کرنی ہیں، 1970–2060۔ ڈیفالٹ: موجودہ سال۔

مثالی درخواست

curl "https://hourora.app/api/v1/zones/America%2FNew_York?year=2027"

مثالی جواب

{
  "id": "America/New_York",
  "aliases": [
    "US/Eastern"
  ],
  "countries": [
    {
      "code": "US",
      "name": "United States"
    }
  ],
  "cities": [
    {
      "slug": "new-york",
      "name": "New York"
    },
    {
      "slug": "philadelphia",
      "name": "Philadelphia"
    },
    {
      "slug": "miami",
      "name": "Miami"
    }
  ],
  "now": {
    "zone": "America/New_York",
    "local": "2026-10-15T07:42:01",
    "iso": "2026-10-15T07:42:01-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-15T11:42:01.270Z",
    "standardOffsetMinutes": -300,
    "dstObserved": true
  },
  "nextTransition": {
    "at": "2026-11-01T06:00:00.000Z",
    "unixMs": 1793512800000,
    "type": "dst-end",
    "fromOffsetMinutes": -240,
    "toOffsetMinutes": -300,
    "shiftMinutes": -60,
    "fromAbbreviation": "EDT",
    "toAbbreviation": "EST",
    "localBefore": "2026-11-01T02:00:00",
    "localAfter": "2026-11-01T01:00:00"
  },
  "year": 2027,
  "dstObservedInYear": true,
  "transitions": [
    {
      "at": "2027-03-14T07:00:00.000Z",
      "unixMs": 1805007600000,
      "type": "dst-start",
      "fromOffsetMinutes": -300,
      "toOffsetMinutes": -240,
      "shiftMinutes": 60,
      "fromAbbreviation": "EST",
      "toAbbreviation": "EDT",
      "localBefore": "2027-03-14T02:00:00",
      "localAfter": "2027-03-14T03:00:00"
    },
    {
      "at": "2027-11-07T06:00:00.000Z",
      "unixMs": 1825567200000,
      "type": "dst-end",
      "fromOffsetMinutes": -240,
      "toOffsetMinutes": -300,
      "shiftMinutes": -60,
      "fromAbbreviation": "EDT",
      "toAbbreviation": "EST",
      "localBefore": "2027-11-07T02:00:00",
      "localAfter": "2027-11-07T01:00:00"
    }
  ],
  "tzdata": "2026e"
}

اس سرور کا حقیقی جواب؛ فہرستیں پہلے 3 آئٹمز تک مختصر کی گئی ہیں۔

شہر تلاش کریں

GET/api/v1/cities

وہ شہر جن کا نام مطابقت رکھتا ہو، بہترین مطابقت اور بڑے شہر پہلے، ہر ایک اپنے ملک، کوآرڈینیٹس اور ٹائم زون کے ساتھ۔

پیرامیٹرز

نام	مطلب
`q`لازمی	شہر کے نام کا کوئی حصہ، اعراب اختیاری (زیادہ سے زیادہ 80 حروف)۔
`limit`اختیاری	کتنے نتائج، 1–50۔ ڈیفالٹ 10۔
`country`اختیاری	ISO 3166 ملکی کوڈ، مثلاً GB، صرف اسی ملک کو رکھنے کے لیے۔

مثالی درخواست

curl "https://hourora.app/api/v1/cities?q=lond&limit=3"

مثالی جواب

{
  "query": "lond",
  "count": 3,
  "total": 7,
  "cities": [
    {
      "slug": "london",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "GB",
        "name": "United Kingdom"
      },
      "region": "Westminster",
      "zone": "Europe/London",
      "lat": 51.5,
      "lng": -0.1167,
      "population": 7994105,
      "capital": true,
      "url": "https://hourora.app/en/london"
    },
    {
      "slug": "londrina",
      "name": "Londrina",
      "asciiName": "Londrina",
      "country": {
        "code": "BR",
        "name": "Brazil"
      },
      "region": "Paraná",
      "zone": "America/Sao_Paulo",
      "lat": -23.3,
      "lng": -51.18,
      "population": 496035,
      "capital": false,
      "url": "https://hourora.app/en/londrina"
    },
    {
      "slug": "london-ontario",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "CA",
        "name": "Canada"
      },
      "region": "Ontario",
      "zone": "America/Toronto",
      "lat": 42.97,
      "lng": -81.25,
      "population": 340900,
      "capital": false,
      "url": "https://hourora.app/en/london-ontario"
    }
  ]
}

اس سرور کا حقیقی جواب۔

ایک شہر

GET/api/v1/cities/{slug}

اس کے slug کے ذریعے ایک شہر، اس کے ٹائم زون کے موجودہ آفسیٹ اور گھڑیوں کی اگلی تبدیلی کے ساتھ۔

پیرامیٹرز

نام	مطلب
`slug`path میں	شہر کا slug، مثلاً tokyo۔

مثالی درخواست

curl "https://hourora.app/api/v1/cities/tokyo"

مثالی جواب

{
  "slug": "tokyo",
  "name": "Tokyo",
  "asciiName": "Tokyo",
  "country": {
    "code": "JP",
    "name": "Japan"
  },
  "region": "Tokyo",
  "zone": "Asia/Tokyo",
  "lat": 35.685,
  "lng": 139.7514,
  "population": 22006300,
  "capital": true,
  "url": "https://hourora.app/en/tokyo",
  "now": {
    "zone": "Asia/Tokyo",
    "local": "2026-10-15T20:42:01",
    "iso": "2026-10-15T20:42:01+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-15T11:42:01.270Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

اس سرور کا حقیقی جواب۔

کوآرڈینیٹس سے ٹائم زون

GET/api/v1/lookup

کسی عرض البلد اور طول البلد کے قریب ترین درج شہر اور اس کا ٹائم زون۔ یہ ایک تخمینہ ہے: زونز کی سرحدیں ماڈل نہیں کی جاتیں۔

پیرامیٹرز

نام	مطلب
`lat`لازمی	اعشاری درجوں میں عرض البلد، −90 سے 90۔
`lng`لازمی	اعشاری درجوں میں طول البلد، −180 سے 180۔

مثالی درخواست

curl "https://hourora.app/api/v1/lookup?lat=48.85&lng=2.35"

مثالی جواب

{
  "query": {
    "lat": 48.85,
    "lng": 2.35
  },
  "approximate": true,
  "method": "nearest listed city (great-circle distance); time-zone borders are not modelled",
  "distanceKm": 2.2,
  "city": {
    "slug": "paris",
    "name": "Paris",
    "asciiName": "Paris",
    "country": {
      "code": "FR",
      "name": "France"
    },
    "region": "Île-de-France",
    "zone": "Europe/Paris",
    "lat": 48.8667,
    "lng": 2.3333,
    "population": 4957589,
    "capital": true,
    "url": "https://hourora.app/en/paris"
  },
  "zone": "Europe/Paris",
  "now": {
    "zone": "Europe/Paris",
    "local": "2026-10-15T13:42:01",
    "iso": "2026-10-15T13:42:01+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-15T11:42:01.270Z"
  },
  "tzdata": "2026e"
}

اس سرور کا حقیقی جواب۔

ڈیٹا ورژن

GET/api/v1/tzdata

جوابات IANA ٹائم زون ڈیٹا بیس کے کس ریلیز سے آتے ہیں، اور Hourora نے آخری بار اپنا ڈیٹا کب اپ ڈیٹ کیا۔

پیرامیٹرز

کوئی پیرامیٹر نہیں۔

مثالی درخواست

curl "https://hourora.app/api/v1/tzdata"

مثالی جواب

{
  "version": "2026e",
  "source": "IANA Time Zone Database",
  "sourceUrl": "https://www.iana.org/time-zones",
  "dataDate": "2026-10-13",
  "range": {
    "from": "1970-01-01",
    "to": "2060-12-31"
  },
  "zones": 344,
  "links": 253,
  "cities": 7269,
  "note": "Outside the compiled range, offsets fall back to the server runtime's own tzdata."
}

اس سرور کا حقیقی جواب۔

خرابیاں

خرابی بھی JSON ہی میں ہوتی ہے: HTTP اسٹیٹس، آپ کے پروگرام کے لیے ایک مستقل کوڈ اور لوگوں کے لیے ایک پیغام۔

{
  "error": {
    "code": "unknown_zone",
    "message": "\"Mars/Base\" is not an IANA time zone name. List them with /api/v1/zones."
  }
}

اسٹیٹس	کوڈز	کب
400	`missing_parameter, invalid_parameter`	کوئی پیرامیٹر موجود نہیں یا متوقع شکل میں نہیں۔
404	`unknown_zone, unknown_city, unknown_country, not_found`	ایسا کوئی ٹائم زون، شہر، ملک یا اینڈ پوائنٹ موجود نہیں۔
429	`rate_limited`	آپ کے کلائنٹ سے بہت زیادہ درخواستیں؛ Retry-After میں دیے گئے سیکنڈ انتظار کریں۔
500	`internal_error`	ہماری طرف کچھ ناکام ہو گیا۔ براہِ کرم بعد میں دوبارہ کوشش کریں۔

یہ کیسے کام کرتا ہے

حدود اور کیشنگ

ہر کلائنٹ فی منٹ 120 درخواستیں بھیج سکتا ہے، اور مختصر اضافے کی گنجائش ہے۔ اس سے آگے API 429 کے ساتھ Retry-After ہیڈر لوٹاتی ہے۔ یہ حد ایک مفت سروس کی حفاظت کرتی ہے؛ اگر آپ کو زیادہ درکار ہو تو کیش کریں۔

ہر جواب بتاتا ہے کہ اسے کتنی دیر کیش کیا جا سکتا ہے (Cache-Control)۔ موجودہ وقت کبھی کیش نہیں ہوتا؛ زونز کی فہرستیں، شہروں کی تفصیلات اور lookups پانچ منٹ کے لیے؛ شہروں کی تلاش اور کسی مخصوص وقت کی تبدیلیاں ایک دن کے لیے۔

گھڑی بنا رہے ہیں؟ آفسیٹ ایک بار حاصل کریں، مقامی طور پر وقت چلائیں، اور جواب میں بتائی گئی گھڑیوں کی اگلی تبدیلی کے بعد دوبارہ حاصل کریں۔ ہر سیکنڈ poll کرنے کی ضرورت نہیں۔

جوابات کہاں سے آتے ہیں

آفسیٹ، مخففات اور گھڑیوں کی تبدیلیاں Hourora کی اپنی مرتب کردہ IANA ٹائم زون ڈیٹا بیس، ریلیز 2026e، سے 1970–2060 کے لیے آتی ہیں۔ اس حد سے باہر سرور کا اپنا بلٹ اِن ڈیٹا استعمال ہوتا ہے، جو پرانا ہو سکتا ہے۔

تبدیلیاں ڈے لائٹ سیونگ کی حدوں کو واضح طور پر حل کرتی ہیں: گھڑیاں آگے ہونے پر چھوڑا جانے والا وقت gap کے طور پر، اور گھڑیاں پیچھے ہونے پر دو بار آنے والا وقت overlap کے طور پر، دونوں لمحات کے ساتھ، بتایا جاتا ہے۔

کوآرڈینیٹس lookup تقریباً 7,200 درج شہروں میں سے قریب ترین اور اس شہر کا زون لوٹاتا ہے۔ کسی سرحد کے قریب، سمندر میں یا کم آبادی والے علاقے میں یہ اس زون سے مختلف ہو سکتا ہے جو اس مقام پر اصل میں لاگو ہوتا ہے۔

استعمال کی شرائط

ذاتی اور تجارتی استعمال کے لیے مفت۔ نہ key، نہ اکاؤنٹ۔
حوالہ دینا سراہا جاتا ہے، لازمی نہیں: جہاں ڈیٹا ظاہر ہو وہاں hourora.app کا لنک۔
جیسی ہے ویسی فراہم کی جاتی ہے، کسی سروس لیول معاہدے یا دستیابی کی ضمانت کے بغیر۔ اسے وہاں استعمال نہ کریں جہاں غلط یا غائب وقت نقصان کا باعث بن سکتا ہو۔
جوابات IANA tzdata 2026e کے مطابق ہیں۔ جب حکومتیں اپنی گھڑیاں بدلتی ہیں تو ڈیٹا اگلے IANA ریلیز کے ساتھ اپ ڈیٹ ہوتا ہے۔
ورژن 1 مطابقت پذیر رہے گا: نئے فیلڈز شامل ہو سکتے ہیں، کچھ ہٹایا یا نام تبدیل نہیں کیا جائے گا۔ مطابقت توڑنے والی تبدیلیاں ‎/api/v2 کے طور پر آئیں گی۔
براہِ کرم ریٹ لمٹ کے اندر رہیں اور جوابات کیش کریں۔ غلط استعمال پر مبنی ٹریفک بلاک کی جا سکتی ہے۔

سوالات

جاننے کی باتیں

کیا Hourora API واقعی مفت ہے؟

جی ہاں۔ نہ key، نہ اکاؤنٹ اور نہ کوئی ادا شدہ درجہ۔ فی کلائنٹ ریٹ لمٹ سروس کو سب کے لیے منصفانہ رکھتی ہے۔

کیا میں اسے براؤزر میں JavaScript سے کال کر سکتا ہوں؟

جی ہاں۔ ہر اینڈ پوائنٹ کسی بھی ویب سائٹ سے cross-origin درخواستوں (CORS) کی اجازت دیتا ہے، اور کسی credentials کی ضرورت نہیں۔

یہ ڈے لائٹ سیونگ ٹائم کو کیسے سنبھالتی ہے؟

ہر جواب IANA قواعد سے عین لمحے کے لیے حساب کیا جاتا ہے۔ convert اینڈ پوائنٹ یہ بھی بتاتا ہے کہ کب مطلوبہ گھڑی کا وقت موجود نہیں (گھڑیاں آگے ہونے پر) یا دو بار آتا ہے (گھڑیاں پیچھے ہونے پر)۔

کوآرڈینیٹس lookup کتنا درست ہے؟

یہ قریب ترین درج شہر کا ٹائم زون لوٹاتا ہے، جو تقریباً ہر اس جگہ درست ہے جہاں لوگ رہتے ہیں۔ یہ زونز کی سرحدیں ماڈل نہیں کرتا، اس لیے سرحد کے قریب یا سمندر میں غلط ہو سکتا ہے۔