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

אזור זמן

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