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

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

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

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

• השמות לתצוגה צריכים להיות ייחודיים בפרויקט שלכם ב-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

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

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

ה-API של קבוצות נתונים של מפות Google לא תומך בקובצי 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 (Well-Known Text)
• 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. אם משתמשים ביחידות שגויות, יכול להיות שהמערך ייבא בהצלחה, אבל הנקודות במערך הנתונים יוצגו במיקומים לא צפויים בנתונים שעבר עיבוד.