לפני שמתחילים

במסמך הזה מתוארים הדרישות המוקדמות, השיטות המומלצות והשגיאות הנפוצות בעבודה עם מערכי נתונים.

דרישות מוקדמות

כשיוצרים מערך נתונים:

• השמות לתצוגה צריכים להיות ייחודיים בפרויקט שלכם ב-Google Cloud.
• שמות לתצוגה חייבים להיות באורך של פחות מ-64 בייטים (מכיוון שהתווים האלה מיוצגים ב-UTF-8, בשפות מסוימות כל תו יכול להיות מיוצג על ידי כמה בייטים).
• התיאורים חייבים להיות באורך של עד 1,000 בייט.

כשאתם מעלים נתונים:

• סוגי הקבצים הנתמכים הם CSV,‏ GeoJSON ו-KML.
• הגודל המקסימלי של קובץ נתמך הוא 500MB.
• שמות של עמודות מאפיינים לא יכולים להתחיל במחרוזת '?_'.
• אין תמיכה בגיאומטריות תלת-ממדיות. זה כולל את הסיומת 'Z' בפורמט WKT ואת קואורדינטת הגובה בפורמט GeoJSON.

הערה: העלאה של קובץ נתונים יכולה להימשך כמה דקות או אפילו שעות, בהתאם לגודל הקובץ. אם תהיה שגיאה בהעלאה, תוצג הודעת שגיאה. אל תנסו למחוק את מערך הנתונים עד שתקבלו תשובה מפעולה ההעלאה.

הערה: יכול להיות ששימוש ב-Maps Datasets API ליצירת משבצות מפה עם נתונים שהועלו יגרום להחרגה או לפשטה של נתונים צפופים או מורכבים ברמות זום נמוכות. לדוגמה, כשמשתמשים מרחיבים את התצוגה למדינה או לאזור (לדוגמה, רמת התצוגה 5-12), ייתכן שהנתונים בחלוקה לריבועים ייראו שונים מאשר כשמרחיבים את התצוגה לעיר או לשכונה (לדוגמה, רמת התצוגה 13-18). המטרה של הפעולה הזו היא לשמור על גודל קטן של המשבצות ועל ביצועים טובים באמצעות שימוש במשבצות עם עיבוד מפה.

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

שיטות מומלצות להכנת נתונים

אם נתוני המקור מורכבים או גדולים, כמו נקודות צפופות, פוליגונים ארוכים או שרשורי קווים ארוכים (לרוב קבצים של מקורות גדולים מ-50MB נכללים בקטגוריה הזו), מומלץ לפשט את הנתונים לפני ההעלאה כדי להשיג את הביצועים הטובים ביותר במפה חזותית.

ריכזנו כאן כמה שיטות מומלצות לעיבוד הנתונים:

1. צמצום המאפיינים של התכונה. שומרים רק את מאפייני התכונות הנחוצים לעיצוב המפה, למשל 'id' ו-'category'. אפשר לצרף מאפיינים נוספים לתכונה באפליקציית לקוח באמצעות סגנונות מבוססי-נתונים במפתח מזהה ייחודי. לדוגמה, תוכלו לקרוא את המאמר הצגת הנתונים בזמן אמת באמצעות עיצוב מבוסס-נתונים.
2. כשאפשר, משתמשים בסוגים פשוטים של נתונים באובייקטים של נכסים, כמו מספרים שלמים, כדי למזער את גודל המשבצת ולשפר את ביצועי המפה.
3. פשטו צורות גיאומטריות מורכבות לפני העלאת הקובץ. אפשר לעשות זאת בכלי גיאו-מרחבי לבחירתכם, כמו הכלי הפתוח Mapshaper.org, או ב-BigQuery באמצעות ST_Simplify בגיאומטריות מורכבות של פוליגונים.
4. לקבץ נקודות צפופות מאוד לפני העלאת הקובץ. אפשר לעשות זאת בכלי גיאו-מרחבי לבחירתכם, כמו פונקציות האשכולות של turf.js בקוד פתוח, או ב-BigQuery באמצעות ST_CLUSTERDBSCAN בגיאומטריות של נקודות צפופות.

הנחיות נוספות לגבי שיטות מומלצות לשימוש במערכי נתונים זמינות במאמר תצוגה חזותית של הנתונים באמצעות Datasets ו-BigQuery.

דרישות GeoJSON

Maps Datasets API תומך במפרט הנוכחי של GeoJSON. ב-Maps Datasets API יש תמיכה גם בקובצי GeoJSON שמכילים את סוגי האובייקטים הבאים:

• אובייקטים גיאומטריים. אובייקט גיאומטריה הוא צורה מרחבית, שמתוארת כאיחוד של נקודות, קווים ופוליגונים עם חורים אופציונליים.
• אובייקטים של תכונות. אובייקט תכונה מכיל גיאומטריה וגם זוגות נוספים של שם/ערך, שהמשמעות שלהם ספציפית לאפליקציה.
• אוספים של תכונות. אוסף תכונות הוא קבוצה של אובייקטים של תכונות.

ב-Maps Datasets API אין תמיכה בקובצי GeoJSON שיש בהם נתונים במערכת צירים (CRS) שאינה WGS84.

למידע נוסף על GeoJSON, ראו תאימות ל-RFC 7946.

דרישות ל-KML

הדרישות ל-Maps Datasets API הן:

• כל כתובות ה-URL צריכות להיות מקומיות (או יחסיות) לקובץ עצמו.
• יש תמיכה בגיאומטריות של נקודות, קווים ופוליגונים.
• כל מאפייני הנתונים נחשבים למחרוזות.

אין תמיכה בתכונות ה-KML הבאות:

• סמלים או <styleUrl> שהוגדרו מחוץ לקובץ.
• קישורים לרשתות, כמו <NetworkLink>
• שכבות-על של קרקע, כמו <GroundOverlay>
• גיאומטריות תלת-ממדיות או תגים שקשורים לגובה, כמו <altitudeMode>
• מפרטי המצלמה, כמו <LookAt>
• סגנונות שהוגדרו בתוך קובץ ה-KML.

הדרישות לגבי קובצי CSV

בקובצי CSV, שמות העמודות הנתמכים מפורטים בהמשך לפי סדר עדיפות:

• latitude, longitude
• lat, long
• x, y
• wkt (טקסט מוכר)
• address, city, state, zip
• address
• עמודה אחת שמכילה את כל פרטי הכתובת, כמו 1600 Amphitheatre Parkway Mountain View, CA 94043

לדוגמה, הקובץ מכיל עמודות בשמות x,‏ y ו-wkt. מכיוון שלעמודות x ו-y יש עדיפות גבוהה יותר, כפי שנקבע לפי סדר שמות העמודות הנתמכות ברשימה שלמעלה, המערכת משתמשת בערכים בעמודות x ו-y ומתעלם מעמודה wkt.

כמו כן:

• כל שם עמודה צריך להיות שייך לעמודה אחת. כלומר, אי אפשר ליצור עמודה בשם xy שמכילה גם נתוני קואורדינטות x וגם נתוני קואורדינטות y. הקואורדינטות x ו-y חייבות להיות בעמודות נפרדות.
• שמות העמודות הם לא תלויי-רישיות.
• הסדר של שמות העמודות לא משנה. לדוגמה, אם קובץ ה-CSV מכיל את העמודות lat ו-long, הן יכולות להופיע בכל סדר.

טיפול בשגיאות בהעלאת נתונים

כשאתם מעלים נתונים למערך נתונים, יכול להיות שתקבלו אחת מהשגיאות הנפוצות שמתוארות בקטע הזה.

שגיאות GeoJSON

דוגמאות לשגיאות נפוצות ב-GeoJSON:

• השדה type חסר או שהערך של type הוא לא מחרוזת. קובץ הנתונים של GeoJSON שהועלו חייב לכלול שדה מחרוזת בשם type כחלק מכל הגדרה של אובייקט Feature ואובייקט Geometry.

שגיאות KML

דוגמאות לשגיאות נפוצות ב-KML:

• אסור לכלול בקובץ הנתונים אף אחת מהתכונות של KML שלא נתמכות, כפי שמפורט למעלה, אחרת ייתכן שהייבוא של הנתונים ייכשל.

שגיאות ב-CSV

דוגמאות לשגיאות נפוצות בקובצי CSV:

• בחלק מהשורות חסרים ערכים בעמודת גיאומטריה. כל השורות בקובץ CSV חייבות להכיל ערכים לא ריקים בעמודות הגיאומטריה. העמודות של הגיאומטריה כוללות:
  • latitude, longitude
  • lat, long
  • x, y
  • wkt
  • address, city, state, zip
  • address
  • עמודה אחת שמכילה את כל פרטי הכתובת, כמו 1600 Amphitheatre Parkway Mountain View, CA 94043
  הערה: השגיאה הזו מתוארת לעיתים קרובות בהודעה בפורמט "לא ניתן להמיר את ' ' למספר כפול" או "לא ניתן לנתח את הקלט לנתונים גיאוגרפיים.: Geography value is missing".
• אם x ו-y הן העמודות של הגיאומטריה, חשוב לוודא שהיחידות הן קו אורך וקו רוחב. במערכי נתונים ציבוריים מסוימים נעשה שימוש במערכות קואורדינטות שונות בכותרות x ו-y. אם משתמשים ביחידות שגויות, יכול להיות שהמערך ייבא בהצלחה, אבל הנקודות במערך הנתונים יוצגו במיקומים לא צפויים בנתונים שעבר עיבוד.