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

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

يتم إنشاء طلبات 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 API استجابة بالتنسيق المحدّد في عنوان URL للطلب.

TimeZoneResponse

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

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

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

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

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

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

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

سلسلة تحتوي على رقم تعريف المنطقة الزمنية، مثل "America/Los_Angeles" أو "Australia/Sydney". يتم تحديد أرقام التعريف هذه من خلال مشروع Unicode Common Locale Data Repository ‏ (CLDR)، وهي متاحة حاليًا في الملف 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 من النتيجة.