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

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

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

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

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

במאמר הצגת נתונים באמצעות מערכי נתונים ו-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 (Well-Known Text)
• address, city, state, zip
• address
• עמודה אחת שמכילה את כל פרטי הכתובת, כמו 1600 Amphitheatre Parkway Mountain View, CA 94043

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

בנוסף, תהליך האישור של MRC לא כולל:

• כל שם עמודה חייב להיות שייך לעמודה אחת. כלומר, אי אפשר להשתמש בעמודה בשם 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
  הערה: השגיאה הזו מתוארת בדרך כלל בהודעה בפורמט "Unable to convert ' ' to a double" או "Could not parse input to geography": חסר ערך גיאוגרפי".
• אם x ו-y הם עמודות הגיאומטריה, צריך לוודא שהיחידות הן קו אורך וקו רוחב. בחלק ממערכי הנתונים הציבוריים נעשה שימוש במערכות קואורדינטות שונות בכותרות x ו-y. אם נעשה שימוש ביחידות שגויות, יכול להיות שהייבוא של קבוצת הנתונים יצליח, אבל הנתונים שיוצגו יציגו את הנקודות בקבוצת הנתונים במיקומים לא צפויים.