درخواست ها و پاسخ های منطقه زمانی

منطقه زمانی

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

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

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

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

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

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

پارامترهای مورد نیاز

• مکان

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

• مهر زمانی

  زمان مورد نظر به صورت ثانیه از نیمه‌شب، ۱ ژانویه ۱۹۷۰ به وقت جهانی. رابط برنامه‌نویسی کاربردی منطقه زمانی (Time Zone API) از timestamp برای تعیین اینکه آیا صرفه‌جویی در ساعت تابستانی باید اعمال شود یا خیر، بر اساس منطقه زمانی location ، استفاده می‌کند.

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

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

• زبان

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

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

مثال‌های منطقه زمانی

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

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

آدرس اینترنتی

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

حلقه زدن

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=1733428634&key=YOUR_API_KEY'

جی‌سون

{
  "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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

حلقه زدن

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

جی‌سون

{
  "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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

حلقه زدن

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'

جی‌سون

{
  "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 درخواست برمی‌گرداند.

منطقه زمانیپاسخ

میدان	مورد نیاز	نوع	توضیحات
status	مورد نیاز	منطقه زمانیوضعیت	برای اطلاعات بیشتر به بخش «وضعیت منطقه زمانی» مراجعه کنید.
dstOffset	اختیاری	شماره	انحراف زمان تابستانی بر حسب ثانیه. اگر منطقه زمانی در طول timestamp مشخص شده در حالت تابستانی نباشد، این مقدار صفر خواهد بود.
errorMessage	اختیاری	رشته	اطلاعات دقیق در مورد دلایل کد وضعیت داده شده. اگر وضعیت غیر از Ok شامل می‌شود.
rawOffset	اختیاری	شماره	انحراف از UTC (به ثانیه) برای مکان داده شده. این مورد شامل صرفه‌جویی در نور روز نمی‌شود.
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 .

منطقه زمانیوضعیت

فیلد status درون شیء پاسخ منطقه زمانی (Time Zone) شامل وضعیت درخواست است. فیلد status می‌تواند شامل مقادیر زیر باشد:

• OK نشان می‌دهد که درخواست با موفقیت انجام شده است.

• INVALID_REQUEST نشان می‌دهد که درخواست ناقص ارسال شده است.

• OVER_DAILY_LIMIT به هر یک از موارد زیر اشاره دارد:

  • کلید API موجود نیست یا نامعتبر است.
  • پرداخت در حساب شما فعال نشده است.
  • از سقف مصرف تعیین‌شده توسط خود کاربر، عبور شده است.
  • روش پرداخت ارائه شده دیگر معتبر نیست (برای مثال، اعتبار کارت اعتباری منقضی شده است).

• OVER_QUERY_LIMIT نشان می‌دهد که درخواست‌کننده از سهمیه تعیین‌شده تجاوز کرده است.

• REQUEST_DENIED نشان می‌دهد که API درخواست را تکمیل نکرده است. تأیید کنید که درخواست به جای HTTP از طریق HTTPS ارسال شده است.

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

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

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

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