درخواست‌ها و پاسخ‌های Time Zone

منطقه زمانی

درخواست‌های Time Zone API به‌صورت رشته نشانی وب ساخته می‌شوند. این میانای برنامه‌سازی کاربردی داده‌های منطقه زمانی را برای نقطه‌ای روی زمین که با جفت عرض-طول جغرافیایی مشخص شده است برمی‌گرداند. توجه داشته باشید که ممکن است داده‌های منطقه زمانی برای مکان‌های روی آب، مانند اقیانوس‌ها یا دریاها، دردسترس نباشد.

درخواست Time Zone به‌صورت زیر است:

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

که outputFormat می‌تواند یکی از مقادیر زیر باشد:

• json (توصیه‌شده)، نشان‌دهنده خروجی در نشان‌گذاری شیء جاوا اسکریپت (JSON)؛ یا
• xml، نشان‌دهنده برونداد در XML است که در یک گره <TimeZoneResponse> قرار گرفته است.

توجه: نشانی‌های وب باید به‌درستی کدگذاری شده باشند تا معتبر باشند و برای همه سرویس‌های وب به ۱۶۳۸۴ نویسه محدود می‌شوند. هنگام ساختن نشانی‌های وب خود، از این محدودیت آگاه باشید. توجه داشته باشید که مرورگرها، پراکسی‌ها و سرورهای مختلف ممکن است محدودیت‌های نویسه نشانی وب متفاوتی نیز داشته باشند.

پارامترهای الزامی

مکان

یک چندتایی عرض جغرافیایی، طول جغرافیایی جداشده با کاما، location=39.6034810,-119.6822510، که نشان‌دهنده مکان موردنظر برای جستجو است.

مُهر زمان

زمان موردنظر برحسب ثانیه از نیمه‌شب ۱ ژانویه ۱۹۷۰ UTC. Time Zone API از timestamp استفاده می‌کند تا براساس منطقه زمانی location تعیین کند که آیا «ساعت تابستانی» باید اعمال شود یا نه.

توجه داشته باشید که API مناطق زمانی تاریخی را درنظر نمی‌گیرد. یعنی اگر مُهر زمان گذشته را مشخص کنید، API این احتمال را که مکان قبلاً در منطقه زمانی دیگری بوده است درنظر نمی‌گیرد.

پارامترهای اختیاری

زبان

زبانی که نتایج به آن برگردانده می‌شود.

• فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
• اگر language ارائه نشده باشد، API تلاش می‌کند از زبان ترجیحی مشخص‌شده در سرصفحه Accept-Language استفاده کند.
• این API تمام تلاش خود را می‌کند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل‌خواندن باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، با رعایت زبان ترجیحی، آن‌ها را به نویسه‌ای که برای کاربر خوانا باشد نویسه‌گردانی می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبانی برگردانده می‌شوند که از مؤلفه اول انتخاب شده است.
• اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
• زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که برگردانده می‌شوند. زمین‌کدیاب اختصارات را بسته به زبان به‌طور متفاوتی تفسیر می‌کند، مانند اختصارات برای انواع خیابان‌ها، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند. برای مثال، utca و tér در زبان مجاری مترادف خیابان هستند.

نمونه‌های منطقه زمانی

این بخش شامل چند پرسمان نمونه است که ویژگی‌های API را نشان می‌دهد.

پرس‌وجوی زیر درخواست منطقه زمانی را برای نوادا، ایالات متحده انجام می‌دهد. مُهر زمان روی ۵ دسامبر ۲۰۲۴ تنظیم شده است.

نشانی وب

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>
      

پرس‌وجوی زیر درخواست منطقه زمانی را برای نوادا، ایالات متحده انجام می‌دهد. مکان همان مکان درخواست بالا است، اما مُهر زمان روی ۱۵ مارس ۲۰۲۴ تنظیم شده است. اکنون پاسخ شامل اختلاف ساعت تابستانی است.

نشانی وب

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>

این مثال شبیه به دو مثال بالا است، اما پارامتر زبان را تنظیم می‌کند. اکنون پاسخ به زبان اسپانیایی بومی‌سازی خواهد شد.

نشانی وب

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 پاسخی را در قالب نشان‌داده‌شده در نشانی وب درخواست برمی‌گرداند.

TimeZoneResponse

فیلد	الزامی	نوع	شرح
status	الزامی	TimeZoneStatus	برای اطلاعات بیشتر، TimeZoneStatus را ببینید.
dstOffset	اختیاری	شماره	فاصله زمانی برای ساعت تابستانی برحسب ثانیه. اگر منطقه زمانی درطول timestamp مشخص‌شده در «ساعت تابستانی» نباشد، این مقدار صفر خواهد بود.
errorMessage	اختیاری	رشته	اطلاعات دقیق درباره دلایل پشت کد وضعیت داده‌شده. اگر وضعیت چیزی غیراز Ok باشد، گنجانده می‌شود.
rawOffset	اختیاری	شماره	فاصله زمانی با UTC (برحسب ثانیه) برای مکان موردنظر. این تنظیم ساعت تابستانی را اعمال نمی‌کند.
timeZoneId	اختیاری	رشته	رشته‌ای حاوی شناسه منطقه زمانی، مانند «America/Los_Angeles» یا «Australia/Sydney». این شناسه‌ها توسط پروژه مخزن داده‌های محلی مشترک Unicode (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 نشان می‌دهد که میانای برنامه‌سازی کاربردی درخواست را تکمیل نکرده است. تأیید کنید که درخواست به‌جای HTTP ازطریق HTTPS ارسال شده است.

• UNKNOWN_ERROR نشان‌دهنده خطای ناشناخته است.

• ZERO_RESULTS نشان می‌دهد که هیچ داده منطقه زمانی‌ای برای موقعیت یا زمان مشخص‌شده پیدا نشد. تأیید کنید که درخواست برای مکانی در خشکی است و نه روی آب.

درحال محاسبه زمان محلی

زمان محلی مکان موردنظر مجموع پارامتر timestamp و فیلدهای dstOffset و rawOffset از نتیجه است.