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

אזור זמן

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

בקשה ל-Time Zone API נראית כך:

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

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

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

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

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 בוחר להחזיר ועל הסדר שבו הן מוחזרות. הכלי להמרת כתובות לקואורדינטות מפרש קיצורים באופן שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הן מילים נרדפות לרחוב בהונגרית.

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

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

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

כתובת URL

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>

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

כתובת URL

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>

הדוגמה הזו דומה לשתי הדוגמאות שלמעלה, אבל היא מגדירה פרמטר שפה. התשובה תהיה בספרדית.

כתובת URL

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 API מחזיר תשובה בפורמט שצוין בכתובת ה-URL של הבקשה.

TimeZoneResponse

שדה חובה סוג תיאור
חובה TimeZoneStatus מידע נוסף זמין במאמר TimeZoneStatus.
אופציונלי number

הסטייה של שעון הקיץ בשניות. הערך יהיה אפס אם אזור הזמן לא נמצא בשעון קיץ במהלך timestamp שצוין.

אופציונלי מחרוזת

מידע מפורט על הסיבות לקוד הסטטוס שניתן. נכלל אם הסטטוס הוא לא Ok.

אופציונלי number

הסטייה משעון UTC (בשניות) במיקום הנתון. השעון לא משתנה לפי שעון הקיץ.

אופציונלי מחרוזת

מחרוזת שמכילה את המזהה של אזור הזמן, למשל "America/Los_Angeles" או "Australia/Sydney". המזהים האלה מוגדרים על ידי פרויקט Unicode Common Locale Data Repository (CLDR)‎, וזמינים כרגע בקובץ timezone.xml. אם לאזור זמן יש כמה מזהים, הפונקציה מחזירה את המזהה הקנוני. בתגובות XML, זהו הכינוי הראשון של כל אזור זמן. לדוגמה, יוחזר "Asia/Calcutta" ולא "Asia/Kolkata".

אופציונלי מחרוזת

השם המלא של אזור הזמן. השדה הזה יותאם לשפה המקומית אם פרמטר השפה מוגדר. לדוגמה: ‫Pacific Daylight Time או Australian Eastern Daylight Time.

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 מהתוצאה.