للمطوّرين

واجهة API للمناطق الزمنية مجانية

المحرّك نفسه الذي يشغّل Hourora، بصيغة JSON بسيطة: الوقت في أي مكان، وتحويلات تراعي التوقيت الصيفي، وكل مناطق IANA وتغييرات ساعتها. دون مفتاح ودون تسجيل.

لمحة سريعة

عنوان URL الأساسي: https://hourora.app/api/v1
الصيغة: JSON (UTF-8)، طلبات GET فقط
المصادقة: لا شيء: دون مفتاح، دون تسجيل، دون ملفات تعريف الارتباط
CORS: مفتوحة لكل المصادر، لذا يمكنك استدعاؤها من المتصفح
حدّ الطلبات: 120 طلب في الدقيقة لكل عميل
بيانات الوقت: IANA tzdata 2026e، من تجميع Hourora
وصف قابل للقراءة آليًا: مستند OpenAPI 3.1

جرّبها مباشرةً

اختر مثالًا أو عدّل المسار، ثم أرسله. يذهب الطلب من متصفحك مباشرةً إلى الواجهة.

الاستجابة

تظهر الاستجابة هنا.

نقاط النهاية

تجيب كل نقطة نهاية على طلبات GET بصيغة JSON. الأوقات بصيغة ISO 8601؛ والفروق بالدقائق شرق UTC (نيويورك في الشتاء −300)، وتُكتب أيضًا نصًا (−05:00).

الوقت الحالي

GET/api/v1/time

الوقت الحالي في منطقة زمنية أو مدينة: التوقيت المحلي، والفرق عن UTC، والاختصار، والتوقيت الصيفي، وتغيير الساعة التالي. دون معاملات: UTC.

المعاملات

الاسم	المعنى
`tz`اختياري	اسم منطقة IANA الزمنية، مثل Europe/London. تُقبل الأسماء البديلة مثل Asia/Calcutta ويُرد عليها بالاسم الحالي.
`city`اختياري	المعرّف النصي للمدينة بدلًا من tz، مثل london (ابحث عن المعرّفات عبر /cities).

مثال على الطلب

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

مثال على الاستجابة

{
  "zone": "Europe/London",
  "local": "2026-10-14T01:59:59",
  "iso": "2026-10-14T01:59:59+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-14T00:59:59.389Z",
  "unixMs": 1791939599389,
  "date": "2026-10-14",
  "time": "01:59:59",
  "weekday": "Wednesday",
  "dayOfYear": 287,
  "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

وقت على الساعة في منطقة ما معروضًا في منطقة أخرى. ويُبلغ عند وقوع الوقت في فجوة التوقيت الصيفي (غير موجود) أو في تداخله (يتكرر مرتين).

المعاملات

الاسم	المعنى
`from`مطلوب	المنطقة (أو معرّف المدينة) التي يُقرأ فيها الوقت.
`to`مطلوب	المنطقة (أو معرّف المدينة) التي يُعرض فيها الوقت.
`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-14T00:59:59.389Z",
  "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 واحدة: أسماؤها البديلة ودولها ومدنها وفرقها الحالي وتغيير الساعة التالي وكل التغييرات في سنة معينة.

المعاملات

الاسم	المعنى
`id`في المسار	اسم منطقة IANA؛ أبقِ الشرطة المائلة أو رمّزها بـ%2F.
`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-13T20:59:59",
    "iso": "2026-10-13T20:59:59-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-14T00:59:59.389Z",
    "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`في المسار	معرّف المدينة، مثل 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-14T09:59:59",
    "iso": "2026-10-14T09:59:59+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-14T00:59:59.389Z"
  },
  "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-14T02:59:59",
    "iso": "2026-10-14T02:59:59+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-14T00:59:59.389Z"
  },
  "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 طلب في الدقيقة، مع السماح بدفعات قصيرة. وبعد ذلك تجيب الواجهة بالرمز 429 مع ترويسة Retry-After. يحمي الحدّ خدمةً مجانية؛ وإن احتجت إلى المزيد فاستخدم التخزين المؤقت.

تذكر كل استجابة المدة التي يجوز تخزينها فيها مؤقتًا (Cache-Control). لا يُخزَّن الوقت الحالي مؤقتًا أبدًا؛ وتُخزَّن قوائم المناطق وتفاصيل المدن وعمليات البحث بالإحداثيات خمس دقائق، وعمليات البحث عن المدن وتحويلات وقت محدد يومًا كاملًا.

تبني ساعة؟ اجلب الفرق مرة واحدة، وعدّ الوقت محليًا، ثم اجلبه مجددًا بعد تغيير الساعة التالي الذي تخبرك به الاستجابة. لا حاجة إلى الاستعلام كل ثانية.

من أين تأتي الإجابات

تأتي الفروق والاختصارات وتغييرات الساعة من نسخة Hourora المجمّعة من قاعدة بيانات IANA للمناطق الزمنية، الإصدار 2026e، للفترة 1970–2060. وخارج هذا النطاق تُستخدم البيانات المدمجة في الخادم، وقد تكون أقدم.

تعالج التحويلات حواف التوقيت الصيفي صراحةً: فالوقت الذي يُتخطّى عند تقديم الساعة يُبلَّغ عنه كفجوة، والوقت الذي يتكرر مرتين عند تأخير الساعة يُبلَّغ عنه كتداخل، مع كلتا اللحظتين.

يعيد البحث بالإحداثيات أقرب مدينة من بين نحو 7,200 مدينة مدرجة ومنطقتها الزمنية. وقرب الحدود أو في البحر أو في منطقة قليلة السكان قد تختلف عن المنطقة المطبّقة فعليًا في تلك النقطة.

شروط الاستخدام

مجانية للاستخدام الشخصي والتجاري. دون مفتاح ودون حساب.
الإشارة إلى المصدر موضع تقدير وليست إلزامية: رابط إلى hourora.app بالقرب من موضع عرض البيانات.
تُقدَّم كما هي، دون اتفاقية مستوى خدمة أو ضمان للتوافر. لا تستخدمها حيث قد يتسبب وقت خاطئ أو مفقود في ضرر.
تتبع الإجابات IANA tzdata 2026e. وعندما تغيّر الحكومات توقيتها، تُحدَّث البيانات مع إصدار IANA التالي.
يبقى الإصدار 1 متوافقًا: قد تُضاف حقول جديدة، ولا يُحذف شيء أو يُعاد تسميته. وستأتي التغييرات غير المتوافقة في /api/v2.
يُرجى الالتزام بحدّ الطلبات وتخزين الاستجابات مؤقتًا. وقد تُحظر حركة المرور المسيئة.

أسئلة

من المفيد معرفته

هل واجهة Hourora API مجانية حقًا؟

نعم. لا مفتاح ولا حساب ولا باقة مدفوعة. ويحافظ حدّ الطلبات لكل عميل على عدالة الخدمة للجميع.

هل يمكنني استدعاؤها من JavaScript في المتصفح؟

نعم. تسمح كل نقطة نهاية بالطلبات عبر المصادر من أي موقع ويب (CORS)، ولا حاجة إلى بيانات اعتماد.

كيف تتعامل مع التوقيت الصيفي؟

تُحسب كل إجابة للحظة الدقيقة وفق قواعد IANA. كما تخبرك نقطة النهاية convert عندما لا يوجد الوقت المطلوب على الساعة (عند تقديم الساعة) أو يتكرر مرتين (عند تأخيرها).

ما مدى دقة البحث بالإحداثيات؟

يعيد المنطقة الزمنية لأقرب مدينة مدرجة، وهي صحيحة في كل مكان تقريبًا يعيش فيه الناس. ولا ينمذج حدود المناطق، لذا قد يخطئ قرب الحدود أو في البحر.