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

منطقه زمانی

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

درخواست «منطقه زمانی» به شکل زیر است:

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

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

• json (توصیه‌شده)، نشان‌دهنده برونداد در نشان‌گذاری شیء جاوا اسکریپت (JSON)؛ یا
• xml، برونداد را در زبان نشانه‌گذاری توسعه‌پذیر نشان می‌دهد که در گره <TimeZoneResponse> پیچیده شده است.

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

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

• مکان

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

• مُهر زمان

  زمان موردنظر برحسب ثانیه از نیمه‌شب ۱ ژانویه ۱۹۷۰ (UTC). «میانای برنامه‌سازی کاربردی منطقه زمانی» از 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 -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 -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 -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	اختیاری	شماره	فاصله زمانی از زمان هماهنگ جهانی (برحسب ثانیه) برای مکان داده‌شده. این کار ساعت تابستانی را درنظر نمی‌گیرد.
timeZoneId	اختیاری	رشته	رشته‌ای حاوی شناسه منطقه زمانی، مثل «America/Los_Angeles» یا «Australia/Sydney». این شناسه‌ها توسط پروژه «مخزن داده‌های مکان مشترک یونیکد» (CLDR) تعریف شده‌اند و درحال‌حاضر در فایل timezone.xml دردسترس هستند. وقتی منطقه زمانی چندین شناسه داشته باشد، شناسه متعارف برگردانده می‌شود. در پاسخ‌های xml، این اولین نام مستعار هر منطقه زمانی است. برای مثال، «آسیا/کلکته» برگردانده می‌شود، نه «آسیا/کلکاتا».
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 از نتیجه است.