طلبات المنطقة الزمنية والردود عليها

المنطقة الزمنية

يتم إنشاء طلبات Time Zone API كسلسلة عناوين URL. تعرض واجهة برمجة التطبيقات بيانات المنطقة الزمنية لنقطة على الأرض، يتم تحديدها من خلال زوج من خطوط العرض وخطوط الطول. يُرجى العِلم أنّ بيانات المنطقة الزمنية قد لا تكون متاحة للمواقع الجغرافية فوق المياه، مثل المحيطات أو البحار.

يتّخذ طلب المنطقة الزمنية الشكل التالي:

https://maps.googleapis.com/maps/api/timezone/outputFormat?parameters

حيث يمكن أن تكون قيمة outputFormat أيًا مما يلي:

  • json (إعداد مقترَح)، يشير إلى الإخراج بتنسيق JavaScript Object Notation (JSON)
  • xml، يشير إلى الناتج بتنسيق XML، ويتم تضمينه ضمن العقدة <TimeZoneResponse>.

ملاحظة: يجب أن تكون عناوين URL مُرمَّزة بشكل صحيح لتكون صالحة، ويجب ألا تتجاوز 16384 حرفًا لجميع خدمات الويب. يجب الانتباه إلى هذا الحدّ عند إنشاء عناوين URL، علمًا بأنّ عدد الأحرف المسموح به في عنوان URL قد يختلف أيضًا باختلاف المتصفحات والخوادم والوكلاء.

المعلمات المطلوبة

  • الموقع

    مجموعة من خطوط العرض والطول مفصولة بفواصل، location=39.6034810,-119.6822510، تمثّل الموقع الجغرافي المطلوب البحث عنه.

  • timestamp

    الوقت المقصود بالثواني منذ منتصف ليل 1 يناير 1970 بالتوقيت العالمي المنسق. تستخدم واجهة برمجة التطبيقات Time Zone API السمة timestamp لتحديد ما إذا كان يجب تطبيق التوقيت الصيفي أم لا، وذلك استنادًا إلى المنطقة الزمنية للسمة location.

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

المعلمات الاختيارية

  • language

    اللغة التي سيتم عرض النتائج بها

    • اطّلِع على قائمة اللغات المتاحة. تعدّل Google غالبًا اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.
    • في حال عدم توفير language، تحاول واجهة برمجة التطبيقات استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language.
    • تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
    • إذا لم يتوفّر اسم باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
    • تؤثر اللغة المفضّلة بشكل بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وفي ترتيب عرضها. تفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما كلمتان مترادفتان لكلمة "شارع" باللغة الهنغارية.

أمثلة على المناطق الزمنية

يتضمّن هذا القسم بعض الأمثلة على طلبات البحث التي توضّح ميزات واجهة برمجة التطبيقات.

ينفّذ طلب البحث أدناه طلبًا للحصول على المنطقة الزمنية في ولاية نيفادا الأمريكية. تم ضبط الطابع الزمني على 5 ديسمبر 2024.

عنوان URL

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 0,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "Pacific Standard Time",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>0.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>Pacific Standard Time</time_zone_name>
</TimeZoneResponse>

ينفّذ طلب البحث أدناه طلبًا للحصول على المنطقة الزمنية في ولاية نيفادا الأمريكية. الموقع الجغرافي هو نفسه المذكور في الطلب أعلاه، ولكن تم ضبط الطابع الزمني على 15 مارس 2024. يتضمّن الردّ الآن قيمة إزاحة نظام التوقيت الصيفي.

عنوان URL

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 3600,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "Pacific Daylight Time",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>3600.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>Pacific Daylight Time</time_zone_name>
</TimeZoneResponse>

يشبه هذا المثال المثالَين أعلاه، ولكنّه يضبط مَعلمة اللغة. سيتم الآن عرض الرد باللغة الإسبانية.

عنوان URL

https://maps.googleapis.com/maps/api/timezone/json?language=es&location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&language=es&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 3600,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "hora de verano del Pacífico",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>3600.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>hora de verano del Pacífico</time_zone_name>
</TimeZoneResponse>

ردود المنطقة الزمنية

لكل طلب صالح، تعرض خدمة Time Zone استجابة بالتنسيق المحدّد في عنوان URL الخاص بالطلب.

TimeZoneResponse

الحقل مطلوب النوع الوصف
مطلوب TimeZoneStatus لمزيد من المعلومات، اطّلِع على TimeZoneStatus.
اختياري الرقم

مقدار الفرق في التوقيت الصيفي بالثواني ستكون القيمة صفرًا إذا لم تكن المنطقة الزمنية في نظام التوقيت الصيفي خلال timestamp المحدّد.

اختياري سلسلة

معلومات مفصّلة عن أسباب رمز الحالة المحدّد يتم تضمينها إذا كانت الحالة غير Ok.

اختياري الرقم

الفَرق بين التوقيت على الجهاز والتوقيت العالمي المنسَّق (بالثواني) للموقع الجغرافي المحدّد ولا يأخذ هذا الإجراء التوقيت الصيفي في الاعتبار.

اختياري سلسلة

سلسلة تحتوي على رقم تعريف المنطقة الزمنية، مثل "America/Los_Angeles" أو "Australia/Sydney". يتم تحديد أرقام التعريف هذه من خلال مشروع مستودع بيانات المواقع المشتركة (CLDR) في Unicode، وهي متاحة حاليًا في ملف timezone.xml. عندما يكون لمنطقة زمنية عدة معرّفات، يتم عرض المعرّف الأساسي. في ردود XML، هذا هو الاسم المستعار الأول لكل منطقة زمنية. على سبيل المثال، يتم عرض "Asia/Calcutta" وليس "Asia/Kolkata".

اختياري سلسلة

تمثّل هذه السمة الاسم الطويل للمنطقة الزمنية. سيتمّت أقلمة هذا الحقل في حال ضبط مَعلمة اللغة، على سبيل المثال: ‫Pacific Daylight Time أو Australian Eastern Daylight Time

TimeZoneStatus

يحتوي الحقل status ضمن عنصر استجابة المنطقة الزمنية على حالة الطلب. قد يحتوي الحقل status على القيم التالية:

  • يشير الرمز OK إلى أنّ الطلب تمّ بنجاح.

  • يشير الرمز INVALID_REQUEST إلى أنّ الطلب تمت صياغته بشكل غير صحيح.

  • يشير الرمز OVER_DAILY_LIMIT إلى أيّ مما يلي:

    • مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح.
    • لم يتم تفعيل الفوترة في حسابك.
    • تم تجاوز الحد الأقصى للاستخدام الذي تم فرضه ذاتيًا.
    • طريقة الدفع المقدَّمة لم تعُد صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).

  • تشير السمة OVER_QUERY_LIMIT إلى أنّ مقدّم الطلب قد تجاوز الحصة المحدّدة.

  • يشير الرمز REQUEST_DENIED إلى أنّ واجهة برمجة التطبيقات لم تكمل الطلب. تأكَّد من إرسال الطلب عبر بروتوكول HTTPS بدلاً من HTTP.

  • يشير الرمز UNKNOWN_ERROR إلى حدوث خطأ غير معروف.

  • يشير الرمز ZERO_RESULTS إلى أنّه تعذّر العثور على بيانات المنطقة الزمنية للموضع أو الوقت المحدّدَين. تأكَّد من أنّ الطلب يتعلق بموقع جغرافي على اليابسة وليس على المياه.

احتساب الوقت المحلي

الوقت المحلي لموقع جغرافي معيّن هو مجموع المَعلمة timestamp والحقلَين dstOffset وrawOffset من النتيجة.