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

אזור זמן

בקשות ל-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.

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