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

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

يتم إنشاء طلبات 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%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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

الحقل	مطلوب	النوع	الوصف
status	مطلوب	TimeZoneStatus	لمزيد من المعلومات، يُرجى الاطّلاع على TimeZoneStatus.
dstOffset	اختياري	الرقم	يشير إلى الفارق بين التوقيت على الجهاز وتوقيت غرينتش بالثواني. ستكون القيمة صفرًا إذا لم تكن المنطقة الزمنية في التوقيت الصيفي خلال timestamp المحدّد.
errorMessage	اختياري	سلسلة	معلومات مفصّلة عن أسباب رمز الحالة المحدّد يتم تضمينها إذا كانت الحالة غير Ok.
rawOffset	اختياري	الرقم	الفَرق بين التوقيت على الجهاز والتوقيت العالمي المنسَّق (بالثواني) للموقع الجغرافي المحدّد ولا تتم مراعاة التوقيت الصيفي في هذه المدة.
timeZoneId	اختياري	سلسلة	سلسلة تحتوي على رقم تعريف المنطقة الزمنية، مثل "America/Los_Angeles" أو "Australia/Sydney". يتم تحديد أرقام التعريف هذه من خلال مشروع مستودع بيانات Unicode Common Locale Data Repository (CLDR)، وهي متاحة حاليًا في ملف timezone.xml. عندما يكون للمنطقة الزمنية عدة أرقام تعريف، يتم عرض الرقم الأساسي. في ردود xml، هذا هو الاسم المستعار الأول لكل منطقة زمنية. على سبيل المثال، يتم عرض "Asia/Calcutta" وليس "Asia/Kolkata".
timeZoneName	اختياري	سلسلة	تمثّل هذه السمة الاسم الطويل للمنطقة الزمنية. سيتم توفير هذا الحقل بلغة أخرى إذا تم ضبط مَعلمة اللغة، مثلاً: ‫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 من النتيجة.