مرجع الواجهة البرمجية

العطلات وحالة التشغيل

تقويمات العطلات للدول والمدن وحالة فتح الأماكن المراعية للعطلات.

العطلات وحالة التشغيل

اجلب تقويم العطلات لدولة (أو مدينة)، واسأل عن العطلة السارية الآن، ودع بطاقات الأماكن تعكس ساعات العطلات تلقائياً.

النطاق المطلوب: places

لماذا يهمّ هذا في منطقة الشرق الأوسط وشمال إفريقيا. في الأردن والسعودية والإمارات والمنطقة الأوسع، تنحني ساعات العمل حول التقويم أكثر بكثير مما هي عليه في الغرب. العيدان يتحرّكان كل عام وفق التقويم القمري؛ الأعياد الوطنية والعطل المصرفية تُغلق المكاتب والخدمات الحكومية؛ وأيام الجمعة (إضافةً إلى ليالي العطلات) تعمل عادةً بساعات مختصرة أو مقسّمة. عبارة ثابتة مثل «مفتوح حتى 23:00» كثيراً ما تكون خاطئة أثناء العيد. توفّر هذه النقاط مصدراً واحداً للحقيقة بتوقيت صحيح، حتى يقول تطبيقك «مفتوح · عيد الفطر · قد تختلف الساعات» بدلاً من عرض وقتٍ خاطئ بثقة.

تُحسب كل الأوقات وفق المنطقة الزمنية الخاصة بالدولة المستهدفة (مثل Asia/Amman لـ JO، وAsia/Riyadh لـ SA، وAsia/Dubai لـ AE)، وليس وفق ساعة المُستدعي.

GET /holidays

تقويم العطلات الكامل لدولة، مع إمكانية تضييقه إلى مدينة و/أو نافذة تواريخ.

النطاق المطلوب: places

curl -s "https://navvo.io/api/v1/holidays?country=JO&from=2026-01-01&to=2026-12-31" \
  -H "x-api-key: nvvo_YOUR_KEY"

معاملات الاستعلام

country

string

رمز الدولة وفق ISO-3166-1 alpha-2 (مثل JO، SA، AE). القيمة الافتراضية JO.

city

string

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

from

string

تاريخ البداية شاملاً (YYYY-MM-DD). يُصفّي العطلات المؤرَّخة/الموسَّعة المُعادة.

string

تاريخ النهاية شاملاً (YYYY-MM-DD).

الاستجابة

مصفوفة من كائنات العطلات:

[
  {
    "id": "jo-independence-day",
    "countryCode": "JO",
    "city": null,
    "name": "Independence Day",
    "nameAr": "عيد الاستقلال",
    "type": "national",
    "recurring": true,
    "month": 5,
    "day": 25,
    "date": "2026-05-25",
    "affectsBusinessHours": true,
    "enabled": true
  },
  {
    "id": "jo-eid-al-fitr-2026",
    "countryCode": "JO",
    "city": null,
    "name": "Eid al-Fitr",
    "nameAr": "عيد الفطر",
    "type": "religious",
    "recurring": false,
    "month": null,
    "day": null,
    "date": "2026-03-20",
    "affectsBusinessHours": true,
    "enabled": true
  }
]

الحقل	النوع	الوصف
`id`	string	معرّف ثابت لمدخل العطلة.
`countryCode`	string	رمز الدولة وفق ISO alpha-2 الذي تنتمي إليه العطلة.
`city`	string \| null	اسم المدينة حين تكون العطلة خاصة بمدينة، وإلا `null` (على مستوى الدولة).
`name`	string	الاسم المعروض بالإنجليزية.
`nameAr`	string	الاسم المعروض بالعربية.
`type`	string	إحدى القيم `public` أو `religious` أو `bank` أو `national` أو `observance`.
`recurring`	boolean	`true` للعطلات ذات التاريخ الثابت التي تتكرّر كل عام (استخدم `month`/`day`)؛ و`false` للعطلات المتحرّكة (استخدم `date`).
`month`	number \| null	الشهر `1`–`12` للعطلات المتكرّرة؛ و`null` للعطلات المتحرّكة.
`day`	number \| null	يوم الشهر للعطلات المتكرّرة؛ و`null` للعطلات المتحرّكة.
`date`	string \| null	تاريخ مطلق بصيغة `YYYY-MM-DD`. يُضبط دائماً للعطلات المتحرّكة؛ وللعطلات المتكرّرة يكون التاريخ المُحلّ ضمن النافذة المطلوبة.
`affectsBusinessHours`	boolean	ما إذا كانت هذه العطلة ينبغي أن تُغيّر طريقة عرض حالة الفتح/الإغلاق.
`enabled`	boolean	ما إذا كان المدخل نشطاً. تُحذف المدخلات المعطّلة عادةً.

المتكرّرة مقابل المتحرّكة. العطلات ذات التاريخ الثابت (الأعياد الوطنية، رأس السنة الميلادية) لها recurring: true وتُفهرس عبر month/day، فتتكرّر سنوياً. أما العطلات القمرية / المتحرّكة — العيدان، ورأس السنة الهجرية، والمولد النبوي — فلها recurring: false وتحمل تاريخاً مطلقاً date للسنة المعنيّة، لأن تاريخها الميلادي يتغيّر. عند تمرير from/to، تُوسَّع العطلات المتكرّرة إلى تواريخ محدّدة داخل تلك النافذة بحيث يكون لكل كائن مُعاد تاريخ date قابل للاستخدام.

GET /holidays/today

العطلة الوحيدة السارية الآن (أو في لحظة مُعطاة) لدولة/مدينة. مثالية لشريط معلومات سريع أو لتقرير ما إذا كنت ستُحاشي على ساعات العمل.

النطاق المطلوب: places

curl -s "https://navvo.io/api/v1/holidays/today?country=JO" \
  -H "x-api-key: nvvo_YOUR_KEY"

# تحقّق من الحالة في لحظة محدّدة (ISO 8601)
curl -s "https://navvo.io/api/v1/holidays/today?country=AE&city=Dubai&at=2026-12-02T09:00:00Z" \
  -H "x-api-key: nvvo_YOUR_KEY"

معاملات الاستعلام

country

string

رمز الدولة وفق ISO alpha-2. القيمة الافتراضية JO.

city

string

مدينة اختيارية، لالتقاط المناسبات الخاصة بالمدينة.

string

لحظة اختيارية بصيغة ISO 8601 لتقييمها بدلاً من الآن (مثل 2026-03-20T08:00:00Z). تُحوَّل اللحظة إلى المنطقة الزمنية للدولة قبل المطابقة، حتى يقع التاريخ على اليوم المحلّي الصحيح.

الاستجابة

{
  "country": "JO",
  "city": null,
  "holiday": {
    "name": "Eid al-Fitr",
    "nameAr": "عيد الفطر",
    "type": "religious",
    "affectsBusinessHours": true
  }
}

حين لا توجد عطلة سارية، تكون holiday بقيمة null:

{
  "country": "JO",
  "city": null,
  "holiday": null
}

الحقل	النوع	الوصف
`country`	string	رمز الدولة المُحلّ.
`city`	string \| null	المدينة المُحلّة، أو `null` إن لم تُطلب.
`holiday`	object \| null	العطلة السارية (`name`، `nameAr`، `type`، `affectsBusinessHours`)، أو `null` إن كان اليوم عادياً.

استخدم affectsBusinessHours لتقرير ما إذا كنت ستُظهر تلميح «قد تختلف الساعات». قد توجد عطلة (مثل observance) دون أن تُغيّر ساعات العمل — في تلك الحالة قد تعرض الاسم مع إبقاء الساعات الاعتيادية.

GET /holidays/on

هل تاريخ محدّد عطلة؟ — لتخطيط "هل سيكون مفتوحاً يوم الخميس القادم؟". يحلّ العطل المتكرّرة (شهر/يوم) وذات التاريخ المطلق في توقيت البلد.

?date=YYYY-MM-DD&country=JO&city=

curl -s "https://navvo.io/api/v1/holidays/on?date=2026-12-25&country=JO" \
  -H "x-api-key: $NAVVO_API_KEY"

{ "provider": "navvo-holidays", "country": "JO", "date": "2026-12-25",
  "isHoliday": true,
  "holiday": { "name": "Christmas Day", "nameAr": "عيد الميلاد المجيد", "type": "religious", "affectsBusinessHours": true } }

اليوم الاعتيادي يعيد isHoliday: false وholiday: null. والتاريخ المُشوَّه يعيد isHoliday: false مع error.

GET /holidays/upcoming

عطل الأيام N القادمة — تُحلّ العطل المتكرّرة إلى موعدها التالي، وتُضمَّن ذات التاريخ المطلق إن وقعت ضمن النافذة، مرتّبةً الأقرب أولاً مع daysUntil.

?country=JO&days=30&city=

{
  "provider": "navvo-holidays", "country": "JO",
  "from": "2026-06-27", "to": "2027-06-27", "days": 365, "count": 4,
  "holidays": [
    { "date": "2026-12-25", "daysUntil": 181, "name": "Christmas Day", "type": "religious", "affectsBusinessHours": true, "city": null },
    { "date": "2027-01-01", "daysUntil": 188, "name": "New Year's Day", "type": "public", "affectsBusinessHours": true, "city": null }
  ]
}

الحقل	النوع	ملاحظات
`from` / `to`	string	نافذة التاريخ المحلولة
`holidays[].date`	string	تاريخ الحدوث المحلول (`YYYY-MM-DD`)
`holidays[].daysUntil`	number	عدد الأيام من اليوم إلى تلك العطلة

حالة الأماكن المراعية للعطلات

لست مضطراً لربط العطلات ببطاقات أماكنك بنفسك — Navvo يفعل ذلك نيابةً عنك. كلٌّ من GET /places/{slug} وGET /places/thumb يتضمّن الآن حقل holiday ويُحاشي على openText عندما تؤثّر عطلة سارية في ساعات العمل.

يستخدم حقل holiday الصيغة نفسها لـ holiday في /holidays/today:

{
  "url": "https://navvo.io/uploads/abc123.webp",
  "source": "logo",
  "rating": 4.6,
  "openState": "open",
  "openText": "Open · until 23:00 · Eid al-Fitr · hours may vary",
  "holiday": {
    "name": "Eid al-Fitr",
    "nameAr": "عيد الفطر",
    "type": "religious",
    "affectsBusinessHours": true
  }
}

كيف يعمل ذلك:

تُحدِّد دولة/مدينة المكان (ومنطقته الزمنية) أي تقويم يُستشار — المنطق نفسه المستخدم في /holidays/today.
عندما تكون لعطلة سارية القيمة affectsBusinessHours: true، يُلحَق بـ openText المقطع · {اسم العطلة} · hours may vary حتى تُبلّغ البطاقة أن الساعات المعلنة غير مؤكّدة أثناء العطلة.
يُعاد كائن holiday المُهيكل دائماً إلى جانب ذلك، حتى تتمكّن من عرض شارتك الخاصة (واختيار name أو nameAr بحسب لغة المستخدم) بدلاً من تحليل openText.
في اليوم العادي، تكون holiday بقيمة null ويبقى openText دون تغيير.

لا يُغلق المكان إغلاقاً قسرياً أبداً. مراعاة العطلات إرشادية فقط. تظلّ openState تُحسب من ساعات العمل المعلنة للمكان؛ وملاحظة العطلة تُحذّر فحسب من أن تلك الساعات قد تختلف. لن يقلب Navvo حالة مكان إلى closed لمجرّد أنه يوم عطلة رسمية — فكثير من المقاهي والمراكز التجارية والصيدليات تبقى مفتوحة (غالباً بساعات عيد خاصة)، فالإشارة الصادقة هي «قد تختلف الساعات»، لا «مغلق».

الأخطاء

الحالة	متى
`400`	تحقّق من الصحة (مثل `from`/`to`/`at` بصيغة غير صحيحة).
`401` / `403`	مفتاح مفقود/غير صالح، أو مفتاح يفتقر إلى النطاق `places`.

العنونة

عنونة برموز Plus Code لمنطقة الشرق الأوسط وشمال إفريقيا — ترميز وفك ترميز وحل عناوين قابلة للمشاركة وقابلة للاشتقاق دون اتصال، بالإضافة إلى إكمال تلقائي متسامح مع الأخطاء بالعربية.

شحن المركبات الكهربائية وتوجيه المدى

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