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

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

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

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

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

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

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

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

الموقع

تمثّل هذه السمة صفًا من خطوط العرض والطول مفصولة بفواصل، 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>

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

بالنسبة إلى كل طلب صالح، تعرض واجهة المنطقة الزمنية ردًا بالتنسيق المحدّد في عنوان 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 من النتيجة.