בקשות ותגובות לגבי אזור הזמן

אזור זמן

בקשות ל-Time Zone API מורכבות כמחרוזת של כתובת URL. ה-API מחזיר נתונים של אזור זמן עבור נקודה על פני כדור הארץ, שצוינה על ידי זוג של קווי רוחב ואורך. שימו לב: יכול להיות שנתוני אזור הזמן לא יהיו זמינים לגבי מיקומים מעל המים, כמו אוקיינוסים או ימים.

בקשה לאזור זמן מופיעה באופן הבא:

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

הערך outputFormat יכול להיות אחד מהערכים הבאים:

• ‫json (מומלץ), מציין פלט בפורמט JavaScript Object Notation ‏ (JSON); או
• ‫xml, מציין פלט ב-XML, עטוף בצומת <TimeZoneResponse>.

הערה: כתובות ה-URL חייבות להיות מקודדות בצורה נכונה כדי להיות תקינות, והן מוגבלות ל-16,384 תווים בכל שירותי האינטרנט. חשוב לזכור את המגבלה הזו כשיוצרים כתובות URL. שימו לב שגם בדפדפנים, בשרתי proxy ובשרתים שונים יכולות להיות מגבלות שונות על מספר התווים בכתובת URL.

פרמטרים נדרשים

• location

  טופל של קו רוחב וקו אורך מופרדים בפסיק, location=39.6034810,-119.6822510, שמייצג את המיקום לחיפוש.

• חותמת זמן

  הזמן הרצוי בשניות מאז חצות, 1 בינואר 1970 ‏UTC. ‫Time Zone API משתמש ב-timestamp כדי לקבוע אם צריך להחיל שעון קיץ, על סמך אזור הזמן של location.

  שימו לב: ה-API לא מתייחס לאזורי זמן היסטוריים. כלומר, אם מציינים חותמת זמן מהעבר, ה-API לא לוקח בחשבון את האפשרות שהמיקום היה בעבר באזור זמן אחר.

פרמטרים אופציונליים

• language

  השפה שבה יוחזרו התוצאות.

  • כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
  • אם לא מספקים את language, ה-API מנסה להשתמש בשפה המועדפת שצוינה בכותרת Accept-Language.
  • ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שקלה לקריאה גם למשתמש וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, הוא מחזיר כתובות רחוב בשפה המקומית, בתעתיק לכתב שהמשתמש יכול לקרוא אם צריך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
  • אם שם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
  • לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו התוצאות מוחזרות. כלי להמרת כתובות לקואורדינטות (geocoder) מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הן מילים נרדפות למילה 'רחוב' בהונגרית.

דוגמאות לאזורי זמן

בקטע הזה יש כמה דוגמאות לשאילתות שמדגימות תכונות של ה-API.

השאילתה שלמטה מבצעת בקשה לאזור זמן בנבאדה, ארה"ב. חותמת הזמן מוגדרת ל-5 בדצמבר 2024.

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",
}

<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. התשובה כוללת עכשיו את ההפרש של שעון הקיץ.

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",
}
        

<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",
}
      

<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

TimeZoneStatus

השדה status באובייקט התגובה של אזור הזמן מכיל את סטטוס הבקשה. השדה status יכול להכיל את הערכים הבאים:

• ‫OK מציין שהבקשה בוצעה בהצלחה.

• ‫INVALID_REQUEST מציין שהבקשה הייתה בעלת מבנה פגום.

• ‫OVER_DAILY_LIMIT מציין את אחת מהאפשרויות הבאות:

  • מפתח ה-API חסר או לא תקין.
  • החיוב לא הופעל בחשבון שלך.
  • הייתה חריגה ממכסת שימוש שהוגדרה על ידי המשתמש.
  • אמצעי התשלום שצוין לא תקף יותר (לדוגמה, תוקף כרטיס האשראי פג).

• OVER_QUERY_LIMIT מציין שהשולח חרג מהמכסה.

• ‫REQUEST_DENIED מציין שממשק ה-API לא השלים את הבקשה. מוודאים שהבקשה נשלחה באמצעות HTTPS ולא באמצעות HTTP.

• ‫UNKNOWN_ERROR מציין שגיאה לא ידועה.

• ‫ZERO_RESULTS מציין שלא נמצאו נתונים של אזור זמן למיקום או לזמן שצוינו. מוודאים שהבקשה היא למיקום ביבשה ולא מעל מים.

חישוב השעה המקומית

השעה המקומית במיקום מסוים היא סכום הפרמטר timestamp והשדות dstOffset ו-rawOffset מהתוצאה.