راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
العثور على المنطقة الزمنية لأي خط عرض وخط طول
الإحداثيات وحدها لا تخبرك بالوقت في نقطة ما على الخريطة. تأخذ نقطة نهاية المنطقة الزمنية خط العرض وخط الطول وتُرجع اسم المنطقة الزمنية وفرق توقيتها الحالي عن UTC واختصارها.
إرسال الطلب
GET /v1/timezone?lat=52.3676&lon=4.9041{
"status": "ok",
"timezone": "Europe/Amsterdam",
"utc_offset": "+02:00",
"abbreviation": "CEST"
}حقل timezone معرّف قياسي يمكنك تمريره مباشرة إلى معظم مكتبات التاريخ والوقت. أما حقلا utc_offset وabbreviation فمفيدان لأغراض العرض حين تريد أن تُظهر للقارئ شيئًا مألوفًا أكثر من سلسلة معرّف.
مثال ثانٍ، على الجانب الآخر من خط التاريخ
فروق التوقيت ليست دائمًا أرقامًا صغيرة ومستديرة، وبعض الأماكن تقع على الجانب الآخر من خط التاريخ بالنسبة إلى معظم سكان العالم.
GET /v1/timezone?lat=-17.7333&lon=168.3273{
"status": "ok",
"timezone": "Pacific/Efate",
"utc_offset": "+11:00",
"abbreviation": "VUT"
}تعامل مع المعرّف المُرجَع بالطريقة نفسها بغض النظر عن مدى بعده عن ساعة خادمك. فمكتبة التاريخ لديك تعرف مسبقًا كيف تتعامل مع فرق توقيت قدره إحدى عشرة ساعة بشكل صحيح، لذا لا توجد حالة خاصة يلزم كتابتها للمواقع البعيدة عن منطقتك الزمنية.
دمجها مع الترميز الجغرافي
لا تحتاج نقطة النهاية هذه إلا إلى الإحداثيات، لذا فهي تقترن بشكل طبيعي بالترميز الجغرافي الأمامي أو العكسي. حوّل العنوان جغرافيًا أولًا للحصول على خط عرضه وخط طوله، ثم مرّرهما مباشرة إلى /v1/timezone لمعرفة المنطقة الزمنية التي يقع فيها ذلك الموقع، دون أن تسأل المستخدم أي شيء عن المناطق الزمنية مباشرة.
اختصار ذو صلة
إذا كان لديك مسبقًا عنوان IP الخاص بالزائر بدلًا من عنوان مرمّز جغرافيًا، فإن نقطة النهاية /v1/ip تُرجع حقل timezone مباشرة ضمن استجابتها، دون أي طلب منفصل إلى نقطة النهاية هذه على الإطلاق. واستخدم /v1/timezone مباشرة حين تكون لديك إحداثيات غير مرتبطة باستعلام عن IP، مثل عنوان من ملف الشحن الخاص بأحد العملاء.
مراعاة التوقيت الصيفي
يعكس حقلا utc_offset وabbreviation فرق التوقيت الساري في الوقت الذي سألت عنه. وإذا كان يهمك تاريخ محدد بدلًا من الوقت الحالي، فمرّر طابعًا زمنيًا بصيغة unix عبر المعامل time لتعكس الاستجابة فرق التوقيت الذي كان ساريًا في ذلك التاريخ، لا فرق توقيت اليوم.
GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000خطأ يستحق التجنب
استدعاء نقطة النهاية هذه مرة واحدة وحفظ قيمة utc_offset مؤقتًا على المدى الطويل اختصار شائع ينكسر مرتين في السنة في الأماكن التي تطبّق التوقيت الصيفي. معرّف المنطقة الزمنية نفسه ثابت وآمن للحفظ المؤقت. أما فرق التوقيت والاختصار فليسا كذلك، لأنهما يتغيران مع التقويم، لذا أعد حسابهما وقت العرض بدلًا من تخزينهما إلى جانب المعرّف.
كم يكلف
كل استعلام عن المنطقة الزمنية يُحتسب طلبًا واحدًا. فإذا كنت تُجري الترميز الجغرافي لعنوان ما ضمن مسار إنشاء حساب أو إتمام شراء، فإن إضافة استعلام عن المنطقة الزمنية للموقع نفسه يضاعف عدد طلباتك في ذلك المسار، من طلب واحد إلى طلبين، وهو ما يبقى ضئيلًا مقارنة بالحصة البالغة 2,500 طلب مجاني يوميًا والمضمّنة مع كل مفتاح.
من السهل الخطأ في بيانات المناطق الزمنية عند التعامل معها يدويًا، خاصة حول حدود التوقيت الصيفي، لذا من الأفضل أخذها من مصدر واحد بدلًا من الاحتفاظ بجدول فروق توقيت خاص بك. ويغطي توثيق الاستعلام عن المنطقة الزمنية القائمة الكاملة للمعاملات.